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A  simple  template  language  makes  It  easy  to  specify  these  directions.  Based  on  the 
line  length  available,  the  output  routine  decides  what  structures  have  to  be 
broken  up  across  multiple  lines  and  produces  the  actual  output  following  the 
directions  created  by  the  formatting  functions.  The  paper  concludes  with 
a  discussion  of  how  the  pretty  printing  method  presented  could  be  applied  to 
languages  other  than  lisp. 
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A  LISP  Pretty  Printer  Providing 
Extensive  User  Format-Control  Mechanisms 

by 

Richard  C.  Waters 

ABSTRACT 

^A  I.isp  pretty  printer  is  presented  which  makes  it  easy  for  a  user  to  control  the  format  of  the 
output  prodtiecd.  Ilie  printer  can  be  used  .is  a  general  mcclianism  for  printing  cUiia  structures 
.'IS  well  as  programs.  It  is  divided  into  two  parts:  a  set  of  formatting  fiinctions.  and  an  output 
routine.  I'he  user  specifies  how  a  particular  type  of  object  slu)uld  be  formatted  by  creating  a 
formatting  function  for  the  type.  When  pas.scd  an  object  of  that  type,  the  formatting  function 
creates  a  sequence  of  directions  which  spextify  how  the  object  should  be  printed  if  it  can  fit  on 
one  line  and  how  it  should  be  printed  if  it  must  be  broken  up  .across  multiple  lines.  A  simple 
template  language  makes  it  easy  to  specify  these  directions,  based  on  the  line  IcngtTl  available, 

Utc  output  routine  decides  what  structures  have  to  be  bn)kcn  up  across  multiple  lines  and 
pnxluccs  tile  actual  output  following  tltc  directions  crctited  by  tlic  formatting  functions.  'Ilie 
paper  concludes  with  a  discussion  of  how  the  pretty  pnnling  method  picsented  could  be 
applied  to  languages  other  tliiin  Lisp. 


Ibis  report  describes  research  done  at  the  Artificial  Intelligence  luiboratury  of  the  Massachusetts  Institute  of 
Technology.  Support  for  the  laboratory's  artificial  intelligence  research  has  been  provided  in  part  by  tlie 
Advanced  Research  Projects  Agency  of  flic  l'X:partnient  of  Defense  under  Office  of  Naval  Research  contracts 
N00014-75-C-0643  and  NOOO 1 4-80-0-0505. 

I'he  views  and  conclusions  contained  in  fliis  paper  arc  those  of  the  author,  and  shouhl  not  lie  interpreted  jis 
neccs.siirilv  representing  the  oflicial  policies,  either  cxpicsscd  or  implied,  of  the  Dcparimcnt  of  Defense,  or  the 
United  Stiiies  Govemment, 
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Introduction 

Most  pretty  primers  are  used  solely  for  fonuatting  program  text.  I  licy  typically  operate  by  reading  in  a 
flic  of  program  text  and  producing  a  formatted  text  flic  as  output.  In  general,  tlicy  have  built-in  knowledge 
specifying  how  eah  syntactic  structure  in  die  programming  language  should  be  formatted  and  ilo  not  give  die 
user  any  significant  control  over  the  fomiat  of  the  output  produced  jl,  .1, 4-')).  With  such  a  pretty  printer,  die 
lack  of  user  fomiat  control  mechanisms  is  tolerable  because  in  most  cases  die  user  cannot  define  any  new 
language  constructs  and  therefore  the  implementors  t»f  the  primers  can  predict  in  advance  all  of  the  structures 
which  die  printer  can  cncoumcr  (and  diough  dicrc  is  no  finn  consensus  on  how  dicsc  stnicturcs  should  be 
fomialtcd  it  is  iiossible  to  select  reasonably  acceptable  formats). 

Some  pretty  printers  (such  as  the  Lisp  primer  presented  here)  are  tisetl  as  part  of  the  programming 
cnvironineni  to  display  infoniiation  to  die  user  radier  dian  as  text  file  processois.  (Note  that  an  inherent 
limihition  of  such  printers  is  that  they  cannot  operate  on  parts  of  a  program  (such  as  comments)  which  appear 
only  in  text  files.)  niese  pretty  printers  do  not  have  to  be  relegated  solely  to  printing  programs.  I'liey  can  be 
just  as  useful  for  printing  data  structures.  If  a  pretty  printer's  use  is  extended  to  user  defined  daUi  stnicturcs, 
user  format  control  mechanisms  become  essential  because  it  is  no  longer  possible  to  predict  what  stnicturcs 
will  be  encountered. 

I^xtcnding  pretty  printers  to  deal  with  data  is  important  because  user  defined  data  stnicturcs  arc  central  to 
almost  any  program.  When  debugging  a  program,  a  programmer  necils  lo  be  able  to  look  at  variotis  data 
items.  I•.very  interactive  pnigramining  environment  supports  the  display  of  the  simple  atomic  data  values 
supported  by  die  language  (such  as  numbers  and  strings).  However,  most  enviroiimcnis  are  not  prepared  to 
print  out  the  contctils  of  complex  user  data  stnicturc’s  in  any  useful  way. 

User  defined  data  abstractions  arc  typically  implcniciitcd  by  combining  together  primitive  data  structures 
(c.g.  vectors,  record  structures,  and  pointers).  A  pretty  printer  can  be  extended  to  deal  with  arbitrary  user 
daiii  abstractions  by  adding  prim  fomials  for  each  basic  data  stnictiire.  l-or  example,  record  stnictiires  might 
be  printed  as  <ficldl  field!  . . .  >  with  each  field  printed  on  a  separate  line  if  die  structure  cannot  be  printed  on 
a  single  line.  Vectors  could  be  primed  analogously  as  [item!  Uem2  . . .  ].  Pointers  could  be  primed  as  ‘8’ 
followed  by  wluit  dicy  point  to.  Suppose  Utat  a  user  has  defined  a  data  abstniction  which  is  iniplcmcntcd  as  a 
record  structure  with  several  fields,  one  of  which  is  a  vector  of  pointem  to  records.  Using  the  jibovc  default 
fomiats.  an  instance  of  (his  abstraction  would  be  primed  as  ibilows  (assuming  that  several  lines  had  to  be  used 
to  print  it). 

<field 

field 

i9<field  ...> 

9<field  ...> 

...] 

. .  .> 

Unfortunately,  this  simple  approach  is  not  very  satisfactory.  The  direct  display  of  the  underlying  data 
structure  which  impicmems  a  data  abstraction  is  not  liable  to  capture  the  user's  idea  of  what  the  data 
abstraction  means,  l-br  example,  some  components  of  the  data  stnicturc  may  not  be  very  impoitiiit  and 
should  not  be  displayed  at  all.  Other  kinds  of  data  slrncturc  coinponcms  (for  example,  circular  pointers) 
cannot  tie  displayed  literally  and  must  be  abbreviated  in  some  way.  Aliernatcly,  it  may  be  useful  to  prim  out 
some  additional  quantities  wliiph.  tliough  not  actually  in  the  structure,  are  useful  for  understanding  die 
structure  (fur  example,  the  names  of  die  fields  or  dcrivcti  values  computed  from  the  field  values). 

\  collaicral  advantage  of  the  rigid  output  format  initially  pmposed  is  that  it  can  be  built  into  die  reader  as 
well  as  the  printer  so  that  it  is  possible  to  recreate  a  data  stnicliirc  by  reading  in  its  printed  representation.  In 
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order  to  maintain  this  readability  property  when  fields  are  being  omitted,  abbreviated,  and/or  added  in  the 
pi'inied  representations  for  data  structures,  tltc  user  must  be  careful  to  insure  that  no  information  is  iiciually 
being  lost,  and  ihc  reader  must  be  modified  to  take  these  special  printed  representations  into  .iccouiit.  In  l  isp 
programming  environments  (for  example  1 10]),  this  kind  (tf  reader  modification  is  usually  possible  tliough  not 
iK'cessarily  easy.  It  should  be  noted  that  in  general  it  is  much  more  imiMirtant  to  print  out  a  data  structure  in  a 
form  whicli  can  be  easily  read  and  understood  by  the  user  than  to  print  it  out  in  a  fonn  which  can  be  read  by 
the  reader. 

Another  serious  problem  with  the  simple  output  scheme  proptKcd  above  is  tltat  the  kind  of  default 
formatting  rules  proposed  almost  never  lead  to  output  which  is  aesthetic.  Ihc  visual  appearance  of  a  data 
structure  has  a  very  important  elTcct  on  its  undcrstandabilily.  I’criiaps  different  delimiters  or  indentation 
would  make  the  daUi  structure  more  readable.  I'crhaps  tire  lli>it  two  fields  arc  closely  related  and  should 
always  be  printed  on  the  siimc  line.  I’crhaps  the  structure  as  a  whole  has  two  quite  separate  logical  parts 
which  should  always  be  printed  on  two  lines. 

In  order  to  deal  witli  these  problems,  it  is  essential  tliat  the  user  be  able  to  control  how  individual  diita 
abstractimis  arc  to  be  printed.  Hie  pretty  printer  Air  I  .isp  presented  in  tJiis  paper  tillows  the  user  to  specify  for 
each  tyiie  of  data  structure  both  w  hat  components  to  print,  and  how  these  components  should  be  foniiatted. 
if  the  printer  is  used  as  lire  standard  printer,  then  lire  user  will  ire  able  to  inspect  his  data  stiiictures  and  sec 
them  printed  out  aesthetically  at  all  times. 

I'retly  printers  arc  typically  conceived  of  as  system  utilities  for  displaying  information  to  the  user. 
However,  a  pretty  printer  can  be  much  more  useful  if  it  can  also  lie  used  as  an  output  facility  which  is  called 
directly  from  user  programs.  The  advantage  of  this  is  tliat  it  makes  available  a  new  paradigm  for  specifying 
output  format. 

Most  high  level  languages  have  f.icilities  for  specifying  how  output  Is  to  be  formatted  on  the  page  (c.g.  the 
1-0111^11  FORMAT  sUiiement).  In  general,  these  Aicilitics  arc  oriented  toward  printing  data  strnctnrcs  whose 
shape  is  know  n  in  advance  on  a  page  whose  width  is  known  in  advance.  Ihercarc  usually  no  facilities  which 
deal  with  variability  in  cillicr  the  shape  of  the  daUi  or  the  width  of  Uie  page.  If  cither  of  these  has  to  be 
paramcteri/cd,  tlien  die  programmer  has  to  write  code  which  computes  how  e.ich  particular  d.ila  structure 
sluuiKI  he  formatted. 

I’retty  printers  are  spccidcally  designed  to  deal  with  variability  in  the  daU  and  in  ihe  space  available. 
When  using  a  pretty  printer,  instead  of  specifying  a  Arnnal  for  die  output  as  u  whole,  the  programmer 
specifics  individual  fonnats  for  e;K:h  of  die  intermediate  stmclurcs  which  can  occur  in  the  ohjcct  to  be 
printed.  Ihese  Amiiats  do  noi  h.ivc  to  be  parlieulaiiy  concerned  with  cither  the  line  width  or  liow  the 
ino.-rmediaie  structures  will  be  combined  togcUicr.  When  priming  a  structure,  die  pretty  printer 
iiiioinatic ally  combines  the  individual  fonnats  and  devitics  where  to  insert  line  breaks  and  blank  space  in 
order  to  make  its  output  fit  rc.Klably  in  the  sp.x'C  available. 

The  saiionrliclow  describe  how  a  particular  l.isp  pretty  piiiitcr(GPRINT)  provides  for  user  Innnat  control 
and  discuss  sonic  of  the  general  issues  involved.  GPRINT  was  originally  implemented  in  IV75  as  an  attempt  to 
improve  on  an  earlier  pretty  printer  implcincnicd  by  GoUIsloin  [.Ij.  Goldstein’s  prcity  printer  is  one  of  the 
few  pretty  printers  which  docs  inekidv  mechanisms  providing  sigiiificaiit  user  control  over  the  format 
pi'viduccil.  liiiA.iiuiiately.  the  mechanisms  lie  provides  arc  at  the  same  time  complex  to  use  and  nut  very 
pow  cifut.  GPRfNT  has  been  rewritten  Amr  limes  most  recently  in  ]98i  in  a  continuing  attempt  to  create  a  u.scr 
citiitiollable  preiiy  printer  with  very  good  human  engineering. 

GPRINI  is  v^riUen  in  l  isp,  and  was  developed  in  die  context  of  a  Lisp  programming  environment.  The 
l  isp  language  is  used  in  this  paper  to  display  paits  of  the  pretty  printing  algoiiihni  and  Lisp  lists  arc  used  in 
examples  (if  how  objects  arc  printed.  I'his  is  done  because  l.is|i  has  several  features  which  make  the 
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imi)lcmcntiition  and  cxplicaliDii  of  a  pretty  printer  particularly  easy.  However,  it  should  be  noted  tliat  the 
ideas  enibvHiied  in  GPRINt  arc  not  limited  to  the  Lisp  domain.  In  particular,  these  ideas  grow  principally  out 
of  the  requirements  for  a  highly  interactive  programming  environment,  rather  tlian  out  of  tlic  I  isp  language. 
Iho  last  sa'tion  of  Uiis  paper  discusses  what  would  be  required  in  order  to  implement  a  similar  pretty  printer 
for  a  programming  environment  other  tlian  Lisp. 

An  Example 

Dcforc  looking  at  GPRINT  in  detail,  consider  die  following  example.  Suppose  a  user  has  denned  a  data 
abstr^iclion  called  NAMED- FORM  with  four  parts:  a  FORM,  which  is  some  arbitrary  Lisp  expression;  a  ROOT, 
which  is  an  identirier  associated  with  the  FORM;  a  SUFFIX,  which  is  used  to  disambiguate  forms  which  have 
die  same  ROOT;  and  a  PARENT,  which  is  a  circular  pointer  pointing  up  to  the  NAMED-FORM  data  structure  which 
contains  this  one.  Together  the  ROOT  and  the  SUFFIX  arc  a  unique  name  for  the  FORM.  The  PARENT  links 
make  it  possible  to  go  backwards  from  a  NAMED-FORM  to  die  NAMED-FORMs containing  it. 

I  he  function  definitions  below  implement  cicccss  functions  and  a  constructor  function  for  diis  data 
abslraclion  implemented  as  a  list,  f  ollow  ing  common  Lisp  programming  practice,  the  symbol  NAMED- FORM  is 
put  in  die  CAR  of  this  list  so  that  instance's  of  die  data  type  can  be  rccogni/.ed  at  run  time. 

(defun  form  (x)  (cadr  x)) 

(defun  root  (x)  (caddr  x)) 

(defun  suffix  (x)  (cadddr  x)) 

(defun  parent  (x)  (car  (eddddr  x))) 

(defun  create-namod-form  (form  root  suffix  parent) 

(list  'named-form  form  root  suffix  parent)) 

If  nothing  more  is  s;ud,  then  NAMED-FORMs  will  be  printed  tmt  in  die  default  format  for  lists  as  follows; 
(NAMEI)-fORM  (+  A  B)  ARG  1  ...) 

There  arc  several  problems  with  this,  first,  there  is  no  goixl  way  to  print  the  circular  parent  pointer  (it  is 
elided  as  ". . ."  above),  l-vcn  if  some  mechanism  is  used  to  keep  the  print  form  finite,  it  will  probably  be  too 
large  to  Iv  readable.  Second,  the  CAR  of  the  list  is  impoilanl  for  computational  reasons  but  it  is  not  a  logical 
part  of  die  structure.  One  might  well  consider  diat  seeing  it  printed  out  is  a  distraction.  Ihird,  the  way  the 
remaining  three  parts  of  the  structure  .ire  printed  out  dtics  nothing  to  imlicatc  their  logical  roles  in  the 
structure.  As  a  resulL  it  is  hard  to  sec  what  is  what. 
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I'hc  Tollowing  example  shows  one  way  in  which  NAMCO-FORMs could  be  more  acsUiclically  displayed. 

AR61;  A  B) 

'I'hc  FORM  is  printed  out  preceded  by  a  tag  formed  by  printing  Ute  ROOT  and  SUFFIX  as  a  single  unit 
Tollowcd  by  a  colon.  Note  that  you  would  not  want  to  store  the  ROOT  and  tlic  SUFFIX  as  a  single  unit  because 
it  is  coniputationally  expensive  to  break  them  apart  However  this  is  easy  for  your  eye  to  do.  I'hc  PARENT 
pointer  is  not  printed  at  all. 

t  he  following  format  definition  could  be  used  to  specify  to  GPRINT  that  NAMED-FORMs  should  be  printed 
out  in  the  above  wjiy.  'I'hc  expression  (DEFUN  (svw/W  :6F0RMAT)  {arg)  My)  defines  die  botly  as  a 
fonuatting  function  which  will  be  used  to  format  lists  with  tlic  indicated  syinbtil  as  llteir  CAR.  When  pas.scd 
such  a  list,  the  function  creates  a  sequence  of  formatting  instructions  specifying  what  should  he  printed 
corresponding  to  the  list  Formatting  functions  can  be  quite  complex.  However,  in  this  example,  tlic 
liirmatting  function  simply  selects  three  of  die  components  of  tlic  data  structure  and  calls  the  function  GF 
(short  for  GPRINT-FORMAT)  in  order  to  create  the  form.itling  instructions. 

(defun  (named-form  :Gformat)  (x) 

(GF  "{2  *  *  -  *}"  (root  x)  (suffix  x)  (form  x))) 

The  function  (GF  template argi  arg2  . . . )  creates  a  sequence  of  formatting  instructions  for  its  arguments 
based  on  dircciions  specified  by  the  template.  (  Templates  arc  discussed  in  detail  below.)  The  template  in  this 
example  can  be  understood  as  follows:  The  {  and  }  siiecify  that  die  components  between  diem  sliould  lie 
trc.ited  as  a  single  logical  unit  when  they  arc  printed  out.  The  2  aller  the  {  spa’ifies  diat  an  indentation  of  2 
should  he  used  inside  this  structure  if  it  has  to  be  broken  up  across  multiple  lines.  The  three  *8  show  where 
the  direc  components  of  die  data  structure  should  be  printed.  The  ’ : '  spaifies  that  a  colon  should  be 
printed  after  tlic  SUFFIX.  Finally,  the  -  specifies  a  conditional  line  break.  If  the  whole  structure  will  not  fit 
on  one  line,  thi  n  a  line  break  will  be  inserted  at  that  point.  Otherwise  a  space  will  be  printed. 

It  is  important  to  realize  that  the  format  dcKS  not  just  specify  how  an  individual  NAMED- FORM  should  be 
printed  in  isolation.  It  is  used  as  part  of  die  s|H’cification  of  how  complex  data  structures  containing 
NAMED- 1  oliMs  should  bc  printed.  For  example,  a  list  of  two  NAMED-FORMs  would  be  printed  as  follows: 

(ARl.l:  (+  A  B) 

CA1LER3:  (-  (+  A  B)  C)) 

The  example  assumes  diat  in  ordci  to  fit  die  structure  into  die  spjicc  available  for  printing,  it  had  to  be 
broken  up  across  two  lines,  llic  oiiterniost  set  of  parentheses  and  die  fact  that  the  two  NAMED-FORMs  arc  lined 
up  vertically  is  coiilrolled  by  the  standard  fonnat  Ibr  lists  of  data.  'Hie  individual  NAMED-FORMs  arc  fonuatted 
as  specified  above. 
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ITic  Basic  Algorithm 

The  central  reatiirc  of  tlic  algoritlim  used  by  GPRINT  is  that  die  pretty  printing  process  is  divided  into  two 
parts  as  shown  in  t-igurc  1.  The  ronnatling  routine  takes  in  an  object  and  creates  a  sequence  of  rorniatting 
instructions  specifying  wliat  to  print.  These  insimetions  specify  how  each  p.irt  of  die  object  is  to  be  printed  if 
it  will  fit  on  one  line,  and  how  it  should  be  printed  if  it  must  be  broken  up  across  multiple  lines.  Ihis 
inftnrnation  is  passed  to  die  output  routine  as  a  sequence  of  entries  in  a  queue.  The  output  routine  operates 
us  a  coroutine  processing  the  queue  entries  as  they  arc  created.  It  daides  how  to  fit  things  into  the  actual 
space  available  and  dien  prints  them. 


OBJECT  ---> 


FORMATTING 

ROUTINE 


— ->  QUEUE 


---> 


OUTPUT 

ROUTINE 


--->  TEXT 


Figure  I ;  Architecture  of  the  basic  pretty  printing  algorithm. 

'Hie  importiince  of  dividing  die  algoridnn  into  two  parts  conics  from  (he  fact  that  it  allows  a  complete 
separation  between  tbnnat  specification  and  the  output  computation.  The  output  routine  is  complex  and 
computation  intensive.  Taken  separately,  it  can  be  designed  to  be  cflicienl  w  iihoiil  compromising  the  need 
for  the  fonnatting  process  to  be  as  clear  and  simple  as  possible.  Similarly,  when  designing  the  formatting 
routine  and  die  user  format  control  mechanisms  it  is  possible  to  concciitratc  on  providing  a  powerful  and 
convenient  interface  to  die  user. 

The  basic  algorithm  described  above  has  liccn  independently  developed  by  several  people  [4, 7)  in 
addition  to  the  auUior.  However,  die  formatting  routines  in  these  other  pretty  printers  arc  very  primitive. 
They  include  only  a  small  set  of  canned  fonnats  and  do  not  allow  for  user  formal  control.  In  (7j,  Oppen  gives 
a  lucid  description  of  the  way  die  output  niuline  operates.  His  discussion  centers  on  the  fact  that  if  the 
l(K)kalicad  used  by  die  output  routine  when  processing  queue  entries  is  appropriately  limited,  dicn  the 
computation  time  required  by  the  output  niutinc  is  linear  in  the  mimlicr  of  queue  entries  created  by  the 
formatting  nnilinc.  Ihc  only  vlificrence  between  his  output  rwitinc  and  GPRlNT’s  output  routine  is  that 
GPR  INT’s  queue  entries  arc  more  general,  'll'  paper  focuses  on  the  unique  aspect  of  GPRINT  --  the  way  the 
formatting  process  allows  for  user  formal  contiol. 
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The  Stiucturc  of  the  Formatting  Routine 

llic  structure  of  (he  fonnatting  routine  is  based  on  tlie  idea  tliat  any  object  to  be  printed  by  GPR INT  can  l>c 
viewed  as  a  directed  graph  wlicre  eacli  terminal  node  is  a  primitive  data  object  (such  ns  a  number  or  a  symbol) 
and  each  non-terminal  node  is  a  composite  data  structure  (such  as  a  list  or  array),  jhe  formatting  routine  is 
organi/cd  around  a  centra)  dispatching  function  (goISPATCH).  At  crtch  niMle,  GDISPATCH  selects  and  calls  an 
appropriate  formatting  function  based  on  various  features  of  die  node  (such  as  its  data  type).  The  formatting 
function  takes  die  node  us  its  argument  and  pushes  entries  onto  the  queue  which  specify  whiit  to  print  and 
how  it  should  be  fonnatted.  Typically,  fonnatting  functions  call  the  dispatching  tunction  recursively  in  order 
to  format  the  composite  components  of  the  node. 

Consider  the  following  simplilied  version  of  GDISPATCH.  Ibis  version  of  GDISPATCH  assumes  that  die 
item  to  be  formatted  must  be  cither  a  number,  a  symbol,  a  string  or  a  list  It  first  tests  die  data  type  of  die 
item.  If  it  is  nut  a  list  then  ATOM-PORMAT  enters  it  diratly  into  die  queue  as  something  to  be  printed  out.  If 
the  item  is  a  list  dien  GDISPATCH  looks  at  die  CAR  of  the  list  in  order  to  pick  a  spaific  formatting  function  to 
call.  Ibe  assiKiation  between  list  CARS  and  formatting  functions  is  recorded  by  storing  the  function  as  die 
:  GF  ORMAT  property  of  die  CAR. 

(dofun  Gdlspatch  (x) 

(cond  ((not  (listp  x))  (atom-format  x)) 

((not  (symbolp  (car  x)))  (funcall  Gnon-symbol-car-format  x)) 

((get  (car  x)  'iGforinat))  (funcall  (get  (car  x)  ’rGformat)  x)) 
((fboundp  (car  x))  (funcall  Gfn-format  x)) 

(T  (funcall  Gsymbol -car-format  *)))) 

If  (here  is  no  special  fomiatting  function  for  a  list  then  GOISPATCH  uses  either  a  default  format  for 
fuiK  iioii  applications  or  a  formatter  for  dati  lists  (ihcst'  formatters  tire  discussed  further  below).  T  hese  default 
torm.iiiors  arc  stored  in  special  variables  so  that  they  tan  be  easily  modified  by  the  user.  In  a  l.isp  .system 
there  is  no  definitive  way  to  distinguish  the  roprcscntalion  of  a  function  call  from  other  kinds  of  list  data.  As  a 
hcurisiie,  CDlSPArCM  looks  to  sec  whether  the  CAR  of  the  list  is  the  name  of  a  currently  dellned  function. 

Hie  acliuil  version  of  GDISPATCH  used  by  GPRINT  is  much  more  general  dian  die  one  presented  here, 
f  irst,  it  can  dispatch  on  additional  features  of  a  list  other  dian  Us  CAR,  Second,  you  can  specify  a  specific 
formal  to  use  when  calling  GPRINT  which  will  override  any  disfialcliing.  Tbird.  GDISPATCH  dispatches  on 
many  uiticr  data  types  as  well  as  lists  (for  example,  arrays).  Tlic  user  fomi.il  control  mechanisms  described 
here  arc  extended  so  that  they  arc  applicable  to  these  other  data  types.  T  his  is  discussed  in  more  detail  below. 

An  important  filing  to  keep  in  mind  about  fonnatting  functions  is  dial  diey  do  not  print  anything  --  rather 
they  specify  a  set  of  directions  to  be  followed  when  GPRINT  prints  an  object  of  die  ass(x;ialcd  type.  In  order  to 
print  sonioilnng  you  call  die  fuiKliun  GPRINT.  It  calls  GDISPATCH  which  calls  fonnatting  functions  which 
create  quciu;  entries  which  arc  interpreted  by  die  output  routine  in  order  to  determine  what  to  print  It  is  die 
output  loiitinc  which  actually  docs  the  printing. 

How  The  Queue  Fjitrics  Specify  Formtilling  Options 

In  order  to  (idly  understand  how  formats  arc  specified,  it  is  important  to  understand  die  cniric's  which  arc 
pudicd  onto  the  c,-.::ue,  riicsc  entries  arc  designed  to  be  a  concise  language  for  spccilyiiig  formatting  options. 

'  /ic  enirics  ci  ode  two  pieces  of  inforniaiioii:  what  should  be  printed  if  an  object  can  be  printed  on  a  single 
nc.  ami  w’  .me  breaks  and  indcnbition  should  be  used  if  the  object  will  not  fit  on  one  line.  The  following 
'SC  Jest,.  <es  die  basic  (|nciic entries. 
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'  Ii(eral'  -  I’l  int  the  literal  text  between  the  apostrophes  in  tJic  output. 

„/i  -  (Underscore)  Print  n  (ilcfault  1)  spaces  in  the  output.  The  argument  can  be  negative  in  w  hich  ease 
the  printing  point  moves  left  but  only  if  there  is  sutlllcicnt  blank  space  to  back  up  over. 

{II  }  -  riicse  two  entries  mark-die  beginning  and  end  of  a  group  of  queue  entries  which  form  a 
substructure  in  the  output.  This  substnicturc  is  treated  as  a  single  unit  when  decisions  about  where 
to  insert  line  bretiks  arc  made.  I'hc  number  following  the  open  bracket  specifies  how  much  die 
indentation  should  he  increased  while  printing  items  inside  the  substructure  when  dicy  w  ill  not  fit 
on  a  single  line.  It  can  be  omitted  in  which  case  it  defaults  to  die  sum  of  die  lengths  of  die  first  direc 
things  printed  in  die  substructure. 

+11  -  (Plus)  This  specifies  a  change  in  indentation.  Ihc  indentation  level  in  the  current  substincture  is 
incremented  by  ii  (default  1 )  which  can  be  negative. 

-//-(minus)  A  conditional  line  break.  Put  a  line  break  in  the  output  if  the  stmettire  immediately 
containing  this  entry  cannot  be  printed  on  a  single  line.  Otherwise,  print  //  (default  1)  spaces  in  die 
output. 

I  -  Always  put  a  line  break  here. 

As  an  example  of  how  formatting  infonnation  is  encoded  in  queue  entries  consider  die  NAMED-FORM 
example  used  above.  When  “PRINT  is  used  to  print  the  list  (NAMED-FORM  (+  A  B)  ARC  1  ...)  the 
formatting  routine  calls  the  specially  defined  formatting  function  (reproduced  below). 

(defun  (namod-form  :6forinat)  (x) 

(GF  "{2  (root  x)  (suffix  x)  (form  x))) 

Uased  on  the  template.  Ihc  call  on  GF  creates  die  following  queue  entries  (assuming  for  simplicity  in  this 
example  diat  (+  A  B)  is  formatted  as  a  single  atom). 

{2  'ARG'  *1'  -  •(+  A  B)'  } 

riie  output  routine  processes  these  queue  entries  as  dicy  arc  created.  It  lets  die  entries  corresponding  to  a 
structure  collect  in  the  queue  until  it  can  determine  whether  or  not  dicrc  is  enough  room  to  print  the  structure 
on  a  single  line.  If  die  available  space  is  long  enough  then  the  entire  structure  will  be  printed  on  a  single  line 
as  follows; 


ARGl:  (+  A  B) 

If  there  is  not  enough  room  then  the  stniclurc  will  be  broken  up.  The  -  queue  entry  indicates  that  in  this 
C.1SC  :i  line  break  should  he  inserted  before  (+  A  B).  Hie  indentation  increment  specifics  dial  the  indcnUition 
should  be  increased  by  two  after  tlic  line  break. 

ARGl: 

(+  A  B) 

If  dierc  is  not  enough  rwim  to  print  die  two  line  form,  then  dicrc  is  no  way  to  print  out  the  structure  which 
is  consistent  with  the  queue  entries.  Iliis  is  an  example  of  the  jliiite  line  leiifil/i  i>robleiii.  Pretty  printers  in 
general  siilTcr  from  this  probU'in  and  there  is  no  simple  solution  to  it.  However,  die  problem  is  usually  not 
severe  as  long  as  the  line  Icnglli  available  for  printing  is  several  times  larger  than  die  largest  indivisible  item 
which  must  be  printed  on  a  single  line.  GPltlNT  has  a  number  of  built-in  I'caiures  (discussed  below)  which  try 
to  ameliorate  this  prohlcm  by  keeping  the  indentation  small  in  order  to  maximi/c  die  line  length  available. 


GPRINT 


-8- 


Wiitcrs 


Fomiatting  Templates 

Queue  entries  arc  created  exclusively  through  the  use  of  the  function  (GF  template argt ur}>2 ...).  GF 
matches  its  template  against  zero  or  more  arguments  and  produces  a  series  of  queue  entries.  Hach  template  is 
a  siring  built  up  out  of  formatting  codes,  'there  arc  tw<i  sets  of  codes,  the  first  set  corresponds  exactly  to  the 
queue  entries  described  in  the  last  section  (i.c.  'literal',  {h  }.  +n,  -//,  and  I).  I'he  second  set  of  codes 
specifics  how  the  template  is  to  be  matched  against  tlie  arguments  to  be  printed.  These  arc  described  in  the 
table  below; 

•  -  Call  GDISPATCH  to  determine  how  to  format  this  objcY't.  If  it  is  an  atom  then  this  creates  a  literal 
queue  entry  for  it.  Kor  example.  (GF  *  ARC)  is  the  same  as  (GF  '"ARG"'). 

I  -  Ignore  the  corrcs|)onding  object. 

[subtemplate']  •  The  part  of  the  object  being  fonnatted  wliich  corresponds  to  this  part  of  the  template 
must  be  a  list.  It  is  decomposed  into  its  elements.  I  hc  template  between  the  square  brackets 
specifics  how  these  arc  to  be  formatted.  For  e.xamplc,  (GF  ''[*-[•-♦]]"  '(1  (2  3)))  is  the 
s.iineas(GF  1  2  3).  Procc.ssing  of  a  snbtemplatc  between  []  terminates  immediately  as 

soon  as  the  corresponding  list  is  exhausted.  1-or  example.  (GF  ■  ( l) )  is  the  same  as 

(GF  1)  and  not  (GF  1).  the  []  codes  have  meaning  only  tt>  GF  and  do  not  by 

themselves  create  any  queue  entries. 

.  -  (Period)  Valid  only  inside  [].  It  specifies  that  the  next  item  is  the  whole  sublist  left  to  process  by  [] 
raihertlian  its  CAR.  For  example,  (GF  "[•-•*]"  ’(1  2))  isthesameas  (GF  1  '(2)). 

<  >  -  This  IS  used  i;isidc  of  []  to  specify  a  template  for  a  list  of  unknown  length.  The  part  of  tire 
template  between  the  angle  brackets  is  taken  as  repealing  indefinitely,  creating  a  subpaltern  of 
infinite  length.  For  example.  "[<*_>]"  is  the  same  as  . .  .]". 

(//  vn/’te/;i;i/at()  '  This  is  an  ablircviation  for  {n  '  [suhtemplalc]' )'}.  this  combines  together 
three  ideas.  First,  it  specifics  that  the  list  should  Ire  treated  as  a  single  siruciurc  in  the  output. 
Second,  it  specifics  that  parentheses  should  be  printed  as  delimiters  tiround  tlie  list.  Third,  it 
specifics  that  the  list  should  be  rlccomposed  using  the  subicmplale  to  specify  bow  its  components 
should  Ire  formatted.  This  format  code  is  a  useful  abbreviation  because  many  list  lirrmats  share 
these  ideas. 

The  number  after  the  open  parenthesis  specifics  the  indentation  intrcmcnl  to  use  in  tire 
substructure.  It  can  be  omiticd  in  which  ease  it  defaults  to  tlte  sum  of  the  lengths  of  the  first  three 
cullies  in  the  substnicturc.  In  this  ease  tlie  first  entry  is  always  an  open  parenthesis.  Typically  the 
second  entry  will  be  tlie  first  item  in  die  list  and  die  third  one  will  Ik'  some  amount  of  blank  space 
after  the  first  item. 

tt  -  This  can  be  used  in  place  of  an  argument  to  any  formatting  code  (c.g.  _,  {},  ( ),  +.  or  -).  It  specifics 
tli.it  the  value  is  to  he  taken  fnim  the  next  input  to  OF.  For  example,  (GF  A'^Ai’B"'  6)  specifics 
th.it  ()  sp.ices  should  be  printed  out  between  the  A  and  Ihc  B. 

Niinl.  White  space  can  be  inscrled  into  a  template  to  give  it  added  readability.  It  has  no  mc.ming  in 
the  template. 

Consider  again  the  simple  template  ("{2  •  •  ~  •}")  used  in  the  examples  above.  Ihc  dircc  *s 

111  uc!i  .iiMiiivt  the  three  iiTuments  to  GF  causing  GDISPATCH  to  be  called  on  each  one  in  tuin.  The  rest  of  the 
("iiti.ii  codes  directly  specify  queue  entries. 
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Simple  Formatting  Functions 

'lliis  section  continues  the  presentation  of  formatting  templates  by  discussing  several  sUindard  l.isp 
program  furnials.  In  GPRINT  die  user  funnat  control  mechanisms  are  used  to  specify  all  of  die  standard 
program  formats,  'lliis  adds  greatly  to  the  clarity  of  die  pretty  printing  algorithm  by  separating  die  format 
specification  from  die  i  cst  of  die  algoridim.  It  also  makes  it  possible  for  the  user  to  modify  die  way  programs 
are  printed  by  changing  the  standard  formats.  It  should  be  noted  that  in  l.isp,  programs  arc  represented  as 
lists  and  arc  treated  just  like  any  other  data  object.  All  die  mechanisms  which  allow  the  user  to  control  the 
fonnat  of  program  lists  can  be  used  to  control  the  fomiat  of  data  strueiurcs  implemented  as  lists. 

I  .isp  function  applications  arc  traditionally  formatted  so  diat  llicy  are  printed  on  a  single  line  or,  if  there  is 
not  enough  room,  so  that  the  arguments  arc  lined  up  vcilically  one  to  a  line.  The  following  function  is  used  as 
the  default  value  of  the  variable  GFN-FORMAT  which  controls  how  function  applications  are  formatted.  'I1ic 
example  printout  shows  liow  a  function  application  looks  when  it  has  to  be  printed  on  more  than  one  line. 

(defun  :Gfn-format  (x)  (GF  "(*_  <•->)*  x)) 

(LIST  Y 

Z) 

The  template  matches  against  the  list  as  a  whole,  printing  parentheses  around  it  in  die  output.  I1ic 
indentation  increment  is  led  unspecified  so  that  it  will  default  to  the  length  of  the  function  name  plus  two 
(one  for  the  open  pareitlhcsis  and  one  for  the  space  printed  alter  die  function  name).  This  causes  the 
arguments  to  line  up  one  under  die  other.  After  the  function  name  is  primed  out  followed  by  a  space,  the 
repetitive  portion  of  the  template  spaiUcs  a  conditional  line  break  alter  each  argument  in  die  function 
application.  Note  that  GDISPATCH  is  called  (via  the  •  format  code)  in  order  to  determine  how  to  format  each 
argument. 

l.isp  assignments  arc  typically  formatted  so  that  each  successive  variabic/valuc  pair  appears  on  a  separate 
line,  lliis  can  be  specified  by  using  the  I  fonnat  code  in  a  template  as  shown.  Ihe  following  DE  F UN  sets  up  a 
formatting  function  which  specifics  diat  this  formal  should  be  used  fur  lists  which  begin  with  the  atom  SETQ. 

(defun  (setq  :Gformat)  (x)  (GF  "(•_  x)) 

(SETQ  Y  1 
Z  Z) 

This  template  is  very  similar  to  die  one  for  function  applications.  I  he  only  difference  is  dial  the  repeadng 
portion  of  the  template  specifies  that  the  arguments  arc  to  be  fomiatlcd  in  pairs  with  a  mandatory  line  break 
allcr  each  pair,  lliis  forces  each  pair  to  appear  tin  a  separate  line  even  when  die  entire  SETQ  could  fit  on  a 
single  line.  Note  that  there  is  no  line  break  before  the  close  parcndicsis  after  the  last  pair  baausc  pr(x;cssing 
in  a  sublemplatc  for  a  list  stops  immediately  as  stHin  as  the  elements  of  the  list  arc  exhausted. 
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The  LET  construct  is  used  to  bind  a  group  of  variables  to  initial  values  and  dien  exaute  a  sequence  of 
statements  in  this  envimnment.  Typically,  die  variable  binding  pairs  are  printed  one  to  a  line  and  die 
statements  arc  printed  one  to  a  line.  A  smalt  indentiition  is  used  for  the  statements  in  order  to  visually 
dilTcrcntiutc  diem  from  die  bound  vai  iabic  pairs  and  in  order  to  keep  the  total  indcnuition  small. 

(dafun  (let  :Gforfflat)  (x)  (GF  "(2  •_  (1  <•!>)  <-•>)"  x)) 

(LET  ((Y  1) 

(Z  2)) 

(CONS  Y  Z)) 

The  template  specifics  an  explicit  indentation  of  2  for  die  statements  in  the  t.ET.  After  die  atom  LET  itself 
is  printed  out,  a  siibtemplatc  specifics  how  die  list  of  bound  variable  pairs  should  be  formatted.  Here  an 
explicit  indentation  of  1  is  used  so  that  dicy  will  line  up  one  under  die  other.  A  I  fonnat  code  is  used  to  force 
each  one  to  appear  on  a  separate  line.  'Hic  final  repetitive  portion  of  the  template  as  a  whole  specifics  a 
conditional  line  break  before  each  statement  in  die  LET.  Note  diat  if  dicrc  is  only  one  bound  variable  pair 
this  allows  the  let  as  a  whole  to  be  printed  on  a  single  line  if  it  will  fit. 

Conditional  expressions  arc  formatted  so  that  each  clause  of  die  conditional  apjicars  on  a  separate  line. 
Ilach  clause  is  composed  of  a  predicate  followed  by  a  sequence  of  suitements.  If  a  clause  will  not  fit  on  a 
single  line,  the  predicate  and  statements  arc  printed  out  one  under  the  other. 

(dafun  (cond  iGformat)  (x)  (GF  "(•_  <  (1  <•->)  I  >  )*  x)) 

(COND  ((MINUSP  Y) 

(-  Y)) 

(T  Y)) 

In  this  icinplaic  the  repetitive  portion  of  die  template  as  a  whole  consists  of  a  subtcniplatc  for  the  clauses 
and  ii  I  format  code  which  forces  each  clause  onto  a  separate  line.  1110  sublemplaie  siiailies  an  explicit 
indiMitaiion  of  1  and  a  conditional  line  break  after  each  expression  in  the  clause. 

The  following  forniatting  function  for  MULTIPLE-VALUE-BINI)  illustrates  the  use  of  the  +  fonnat  code.  In 
order  to  highlight  the  dillcrencc  between  diem,  the  form  which  returns  the  multiple  values  is  printed  at  an 
indentation  of  4  while  die  statements  which  use  die  bound  values  arc  printed  at  an  indcnUition  of  2.  Ilic 
indeiitatioii  is  initially  spaified  as  4.  Ilic  subtcniplatc  dicn  prints  out  the  list  of  bound  variables.  After  die 
multiple  value  returning  fonn  is  printed  the  indentation  is  dcercmcnlcd  by  2.  llie  repetitive  portion  of  die 
template  dicii  prints  out  the  remaining  forms  one  to  a  line  at  an  indentadon  of  2. 

(defun  (multlple-value-bind  iGformat)  (x)  (GF  "(4*_  (<•_>)  -•  +-Z  <-•>)"  x)) 

(MULTIPLE-VALUE-BIND  (SYMBOL  ALREAOY-THERE-P) 

(INTERN  STRING) 

(COND  (ALREADY-THERE-P  (ERROR  "Symbol  already  there:  "  STRING))) 

SYMBOL) 
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As  a  nnal  example,  consider  the  Function  QUOTE,  A  list  which  begins  with  the  aumi  QUOTE  is  not  printed 

with  parentlrcscs  around  it.  Ratlier.  tlic  argument  to  QUOTE  is  printed  out  following  a . .  Iltc  example 

shows  the  way  the  list  (QUOTE  A)  is  formatted. 

(defun  (quote  ;Gfortnat)  (x)  (GF  "{’"'[I  •]}“  x)) 

'A 

'llie  template  sets  up  a  suhstructure  and  prints  a  "  • "  (inside  of  a  literal  in  a  template,  "  ’  stands  for . ). 

It  then  prints  out  the  argument  to  QUOTE.  Note  how  it  uses  the  format  codes  []  and  I  in  order  to  select  out 
this  argument. 


More  Complex  Formatting  Functions 

A  wide  variety  of  fonnats  can  be  spccilled  using  simple  formatting  functions  like  those  above  which 
contain  only  a  single  call  on  the  function  GF.  However,  these  formats  are  ivsuicted  in  several  ways.  In 
particular,  with  tltese  simple  formatting  functions  it  is  not  possible  to  vary  Hie  fonnnt  based  on  the  actual  data 
values  in  a  structure.  More  conifilex  formats  can  be  specified  by  taking  advantage  of  llie  fact  tliat  a  formatting 
function  can  contain  arbitrtiry  computation. 

I'or  example,  consider  the  following  way  in  which  tltc  fonnal  for  NAMED-FORMs  coulil  be  extended. 
Suppose  that  the  sufllx  field  in  a  NAMEO-FORM  is  optional  and  that  a  value  of  NIL  indicates  that  tlierc  is  no 
suflix.  In  Uiis  case  we  lio  not  want  to  print  tlie  sufllx  at  all.  ITtc  example  shows  how  the  list 
(NAMEO-FORM  (+  A  B)  ARG  NIL  ...) should bc printed. 

(defun  (named-form  :Gformat)  (x) 

(GF  "{2  »"  (root  x)) 

(cond  ((not  (null  (suffix  x)))  (GF  (suffix  x)))) 

(GF  (form  x))) 

ARG;  (a-  A  B) 

In  the  above  format  definition  the  single  template  used  in  tlic  fonnal  definition  in  the  beginning  of  this 
paper  is  broken  into  three  pieces.  A  conditional  test  is  inserted  so  dial  printing  of  the  sulTlx  only  occurs  when 
it  is  non-null.  T  he  {  and  }  indicating  ilic  beginning  .ind  end  of  the  siibsiructiirc  of  queue  entries  being 
erc.ilcU  arc  specified  in  scp.iiiite  ctills  on  GF.  Tliis  is  a  common  occurrence  and  is  in  contrast  to  [] 
(and  therefore  ())  which  must  be  properly  nested  in  a  single  call  on  GF. 

OT  all  of  the  formats  in  Uiis  p.ipcr,  this  is  perhaps  Uic  best  example  of  the  way  GPRIMT  is  typically  used. 
Some  simple  templates  arc  combined  with  some  simple  computation  in  order  to  define  a  flexible  and 
aesthetic  fonnal  for  a  data  object. 


GPRINT 


-12- 


Waters 


Hlock  Form  and  Tabular  Form 

In  order  to  ivive  space,  long  lists  of' data  arc  of\cn  roimatted  in  hlin  k  fonn  where  as  many  items  as  possible 
arc  put  on  each  line.  The  language  which  is  used  to  create  formatting  templates  has  two  format  codes  which 
arc  useful  fur  specifying  tliis  kind  of  format 

,  n  -  (Comma)  A  line  break  is  inserted  here  if  and  «)idy  if  the  structure  immediately  following  this  code 
will  not  tit  on  tlic  end  of  die  current  line.  Otherwise  it  (default  I)  spaces  are  printed. 

;  n  -  (Semicolon)  I'his  is  the  same  as  the  comma  format  except  dial  additional  spacing  is  inserted  so  that 
die  items  printed  out  line  up  in  a  tabular  fasliion.  The  argument  n  specifies  what  spacing  to  use 
between  the  columns  in  the  table.  If  it  is  omitted  a  default  value  will  be  chosen  by  the  output 
routine  based  on  the  lengths  of  the  items  to  be  printed  out 

Hie  following  formatting  function  can  be  used  to  print  out  a  list  in  block  fonn. 

(dofun  :Glb1ock  (x)  (GF  "(1  <*.>)”  x)) 

(OllANGE  PEAR  (RED  APPLE)  GRAPEFRUIT 
(HAWAIIAN  PINEAPPLE)  BANANA 
CANTALOUPE  POMEGRANATE  TANGERINE) 

There  is  a  problem  with  printing  lists  of  data  in  bhK'k  fonnat  If  the  elements  of  a  list  arc  themselves  lists 
with  a  depth  of  greater  than  one.  then  die  output  is  not  very  aesthetic  because  it  is  not  easy  to  iilentify  die 
elements  of  the  top  level  list,  for  example,  consider  the  following  list; 

((CHANGE  (SELL  .1))  (PEAR  (BUY  10))  ((RED  APPLE)  (BUY  5)) 

((UtAPEFRUIT  (HUY  10))  ((HAWAIIAN  PINEAPPLE)  (SELL  8)) 

(IIANANA  (SELL  Ei))  (CANTALOUPE  (BUY  4))) 

Hie  following  formatting  function  uses  die  semicolon  format  code  in  order  to  print  otit  lists  in  a  tabular 
format.  It  is  used  as  the  default  value  ol  the  special  variables  GSYMBOL-CAR- FORMAT  and  GNON-SYMBOL- 
CAR-EORMAT  which  coiilrol  how  lists  of  data  arc  printed.  Ihis  makes  the  output  much  easier  to  rcail  without 
taking  up  very  nuich  more  space. 

(d^iEiin  :GlTblock  (x)  (GF  "(t  <•;>)"  x)) 

({ORANGE  (SELL  3))  (PEAR  (BUY  10)) 

((RED  APPLE)  (BUY  5))  (GRAPEFRUIT  (BUY  10)) 

((ttAWAIIAN  PINEAPPLE)  (SELL  8)) 

(BANANA  (SELL  5))  (CANTALOUPE  (BUY  4))) 

Doc  to  the  fict  that  the  output  routine  uses  only  limited  Umk  ahead,  die  tab  size  must  usually  Ik  chosen 
hcfoic  all  of  die  elements  in  the  list  have  been  entered  in  the  queue.  As  a  rcsulL  it  is  not  guaranteed  to  be 
large  enough.  In  this  example,  the  fourth  element  in  die  list  was  not  completely  entered  in  the  queue  at  the 
time  when  it  was  dciennincd  that  the  list  had  to  be  put  on  more  than  one  line.  As  a  rcsulL  only  die  first  three 
elements  wcic  used  to  dctcmiinc  the  tab  si/c  which  turned  out  to  be  loo  small  to  accommodate  the  (Iflh 
element. 
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Functional  Siiblcm  plates 

the  following  format  codes  increase  tlie  tlexibility  of  tlic  templates  by  making  it  possible  to  call  functions 
at  different  points  in  a  template. 

Xf  -  This  specifics  that  titc  function  /  should  be  called  in  order  to  format  the  corresponding  item.  Ihc 
end  of  the  function  name  is  delimited  by  a  space. 

$/-(IX)llar  sign)  Ihis  command  specifics  tliat  GOISPATCH  should  be  called  in  order  to  format  tlic 
corresponding  item,  but  that  Ihc  function  /  should  be  passed  to  GOISPATCH  as  a  suggestion  of  how 
to  format  the  item.  As  above,  the  end  of  the  function  name  is  delimited  by  a  space.  Ihc  difference 
between  $/  and  Xf  is  that  with  $/  GOISPATCH  gets  control.  As  a  result,  if  the  item  is  not  a  list,  then 
the  function  /  will  not  get  used. 

The  use  of  tlic  $  code  is  illustrated  in  the  following  fonnat  which  block  formats  a  tree  at  all  levels.  It  is 
capable  of  foniialling  trees  of  arbitrary  dcptli  because  it  explicitly  calls  itself  recursively.  GbISPAI  CH  is  called 
at  each  level  of  the  recursion.  As  a  result,  as  soon  as  an  atom  is  encountered,  tlic  i  ccursion  is  terminated  and 
die  atom  is  printed  normally. 

(defun  :Gb1ock  (tree)  (GF  ”(l<$:Gb1ock  ,>)"  tree)) 

(ONE  (TWO  THREE) 

((FOUR  FIVE)  SIX 
SEVEN) 

EIGHT  NINE) 

Ihc  following  formalling  function  for  PROG  uses  %  so  tiiat  it  can  call  a  subfomiat  (GPROG-FORMATZ) 
wiilioul  GOISPATCH  being  called.  This  is  ncccssiiry  so  diat  the  labels  (which  arc  atoms)  in  the  PROG  will  be 
priKcsscd  by  GPROG-FORMATZ.  Labels  arc  printed  lell shifted  by  computing  negative  arguments  for  _. 

(declare  (special  Gwas*1abe1)) 

(defun  (prog  iGformat)  (list) 

( let  (Gwas-label ) 

(GF  "(*_$:Gblock  CHGprog-formatZ  >)"  list))) 

(defun  Gprog-formatZ  (Item) 

(cond  ((not  Gwas-label)  (GF  "I"))) 

(cond  ((atom  item)  (setq  Gwas-label  T) 

(GF  (-  (1+  (flatsize  Item)))  item)) 

(T  (GF  "*"  item)  (setq  Gwas-label  nil)))) 

(PROG  (RESULT) 

L  (COND  ((NULL  LIST)  (60  THE-ENO))) 

(SETQ  RESULT  (CONS  (CAR  LIST)  RESULT)) 

(SETQ  LIST  (COR  LIST)) 

(GO  L) 

THE-END  (SETQ  RESULT  (NREVERSE  RESULT)) 

(RETURN  RESULT)) 

An  important  aspect  of  the  last  example  is  the  way  it  interacts  widi  length  abbreviation  (described  below) 
and  other  standard  facilities  provided  by  GPRINT.  Since  length  abbreviation  is  implemented  by  [].  in  order 
to  get  length  abbreviation  to  apply  to  die  formats  you  write,  you  have  to  use  [].  This  is  an  unportani  reason 
for  writing  it  in  (he  fonn  given  above  rather  than  as  a  single  routine  containing  a  loop  which  decomposes  die 
list  itself  and  creates  (he  correct  format  codes. 
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Miser  Mode 

GPRINT  provides  several  facilities  which  help  deal  with  the  finite  line  length  problem.  Hie  most 
coniprchcnsiic  of  tlicsc  is  a  modified  form  of  tlic  miser  mode  .supported  by  (loldstcin’s  pretty  printer  (.1|.  The 
point  at  which  miser  mixlc  is  triggered  is  controlled  by  the  variable  MISER-WIDTH  (which  defaults  to  40).  If 
the  line  width  available  for  printing  is  less  than  MISER-WIDTH,  tlicn  miser  mode  is  triggered,  and  formatting  is 
modified  in  two  ways.  First,  all  indentations  inside  {}  formats  are  forced  to  be  I  no  matter  what  is  specified. 
Second,  all  +  formats  arc  ignored  so  that  die  indentation  remains  1  in  each  substructure.  In  addition  to  this,  a 
formatting  command  (M)  is  provided  so  that  the  user  can  specify  line  breaks  which  should  only  hapjien  when 
miser  mode  is  triggered. 

M  -  A  line  break  is  inserted  here  if  and  only  if  the  containing  structure  cannot  be  printed  on  one  line, 
and  the  width  available  for  printing  is  less  than  MISER-WIDTH. 

-  (  Tilde)  Print  n  (default  1)  spaces  in  die  output.  Hie  argument  can  be  negative  in  which  ease  die 
printing  point  moves  left  if  dicre  is  sufficient  blank  space  to  back  up  over. 

(Underscore)  'lliis  is  actually  an  abbreviation  for  ~hM.  It  therefore  specifics  a  miser  mode  line 
break. 

In  order  to  see  how  miser  mode  works,  consider  die  format  for  multiple-VALUE-bind  reproduced 
below.  The  example  shows  the  fonnat  which  diis  specifics  in  miser  mode.  The  indentation  increment  is 
reduced  to  a  constant  1,  and  the  occurrences  of  _  lead  to  line  breaks  when  misering.  Ilic  Siitnc  effects  can  be 
.seen  in  die  COHO. 

(dofun  (mu1t1ple-va1u0-b1nd  iGformat)  (*)  (GF  "(4»_  (<•_>)  -•  +-2  <-*>)"  x)) 

(MULTIPI  E-VALUE-BINO 
(.SYMBOL  ALREADY-tHERE-P) 

(INIHKN  STRING) 

(CONI) 

( AI.READY-THERE-P 
(ERROR 

".Symbol  already  there:  " 

SIRING))) 

SYMBOL) 

In  order  lo  maintain  some  of  the  indentation  pattern  of  MULTIPLE-VALUE-BIND  in  miser  mode,  the  - 
format  code  could  be  used  in  place  of  _  and  +  as  shown  below. 

(defun  (multiple-valuo'bind  :Gformat)  (x)  (GF  "(2»-  (<•_>)  -  ~2*  <-•>)"  x)) 

(MULTIPI.r-VALUE-BIND  (SYMBOL 

ALREADY-THERE-P) 

(INTERN  STRING) 

(COND 

(ALREADY-THERE-P 

(ERROR 

"Symbol  already  there:  " 

STRING))) 

SYMBOL) 

Thri'ugh  judicious  choice  of  when  to  use  ~  instead  of  _  or  +,  the  user  can  gain  considerable  control  over 
how  a  form:ii  will  look  in  miser  mode.  However,  as  can  he  sc*cn  above,  miser  mode  is  not  particularly 
loilicuc  III)  iii.iitoi  what  you  do.  It  exists  solely  ;i$  an  emergency  measure  to  prevent  printout  from 
overrunning  ;hc  right  margin. 
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l.eft  Shifting  of  Major  Units 

Another  way  in  which  GPRINT  deals  with  tltc  finite  line  lengtli  problem  is  to  tike  logical  units  orprogiaiu 
text  (such  as  LETS,  PROGs,  and  DOs)  and  shift  them  left  in  order  to  increase  the  amount  of  line  width  available. 
Iliis  prcKCSS  is  triggered  when  tlic  line  width  available  for  printing  is  less  than  MAJOR -WIDTH  (which  defaults 
to  40).  l  eft  shifting  is  illustrated  in  the  example  below,  llic  radical  reduction  in  indcnbition  is  very  effective 
at  increasing  the  width  available.  Unfortunately,  the  nonstandard  format  reduces  readability.  This  problem  is 
ameliorated  by  the  fact  that  an  entire  logical  unit  is  being  left  shifted,  not  some  arbitrary  part  of  the  program. 

(defun  (let  :Gformat)  (list) 

(Gcheck-indentation  list 

#'(1ambda  (x)  (GF  "(2  •_(!  <•!>)<-•>)"  x)))) 

(defun  Gcheck-indentation  (list  format-fn) 

(let  ((ind  (Gestlmate-indent))) 

(cond  ((>  (-  Glinelen  ind)  major-width)  (GF  list  format-fn)) 

(T  (GF  . ’-(Ifl’!"  (-  ind)  (-  ind  11.)) 

(GF  (-  5  ind)  list  format-fn) 

(GF  "1-#’: . . '-ifl’l"  (-  ind)  (-  ind  11.)))))) 

(DEFUN  ROOTS-OF-QUADRATIC  (A  B  C) 

(COND  ((MOT  (ZEHOP  A)) 

(LET  ((DISCRIMINANT  (-  (*86)  (•  4  A  C)))) 

(COND  ((PLUSP  DISCRIMINANT) 


(LET  f(TERMl  (-  B)) 

(TERM?.  (SORT  DISCRIMINANT)) 

(TERM3  (*  2  A))) 

(LIST  (//  (+  TERMl  TERM2)  TERMS) 

(//  (-  TERMl  TERM2)  TERM3))) 

: .  I 

)))))) 

I  efl  shifting  is  implcniented  by  the  foniiatting  function  GCHECK-INDENTATION.  I'he  use  of  this  function 
is  illustrated  by  the  formatting  function  for  LET  shown  above.  It  calls  GCHECK-INDENTATION  passing  it  tlic 
simple  fomi.’itting  function  for  LET  which  was  described  in  tlie  beginning  of  tliis  paper. 
GCHECK-INDENTATION  calls  the  ftinction  GESTIMATE-INOENTAl  ION  which  looks  at  the  queue  of  fomiatting 
commands  and  determines  what  indentation  will  he  used  when  printing  out  the  LEI .  Note  that  tins  must  be 
computed  from  die  queue  because  there  may  be  many  entries  in  the  queue  which  have  not  yet  been  printed. 

If  the  width  available  for  printing  is  greater  than  MAJOR-WIDTH  dien  GCHECK-INDENTAflON  just  calls  the 
fonnatiing  function  passed  to  it.  (Note  Uiat  if  the  &  format  cixlc  was  used  instead  of  X,  GOISPATCH  would 
think  that  it  was  encountering  a  second  (circular)  reference  to  the  list  being  printed  and  abbreviate  it  as 
described  in  die  next  section).  If  the  width  available  is  less  than  MAJOR-WIDTH  then  GCHECK-INDENTATION 
spaces  back  to  column  zero  and  prints  a  comment  line  which  indicates  that  left  shilling  is  cxxumng  using  a 
"  I "  to  show  the  indentation  which  otherwise  would  have  been  used.  On  the  next  line,  the  format  spaces  back 
to  column  5  and  calls  the  fomiatting  function  passed  to  it  in  order  to  formal  the  list  being  printed.  I'inally,  it 
prints  another  comment  line.  Note  duit  the  templates  make  heavy  use  of  tlic  0  format  code  so  tliat  the 
function  can  compute  the  appropriate  ncgiitivc  spacing. 
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Abbreviation 

GPRINT  provides  several  different  abbreviation  mechanisms.  First,  there  is  abbreviation  basetl  on 
PRINLEVEL  and  PRINLENGTH  as  in  the  standard  printer.  A  is  printed  for  structures  which  arc  tin)  deep, 
and  " ..."  is  printed  in  place  of  the  ends  of  lists  which  arc  t«H)  long.  Hie  following  example  shows  how  the 
list(l  (2  (3  (4)))  A  B  C)  woiildappcarwithPRINLEVELandPRINLENGTHbothsctto3. 

(I  (2  (3  ..))  A  ...) 

There  is  a  separate  abbreviation  facility  based  on  die  variables  PRINSTARTLINE  and  PRINENOLINE.  As 
GPRINT  prims,  it  counts  the  lines  starting  with  zero  for  the  line  Uie  printer  is  called  on.  While  Uic  line  nuinber 
is  less  than  PRINSTARTLINE  no  actual  printing  is  done.  If  the  line  number  ever  becomes  greater  tlian 
PRINENOLINE,  then  tJic  printer  prints  " — "  to  indicate  Uiat  truncation  has  occurred  and  immediately  slops 
printing  and  returns  nonnally.  l-xpcrimentation  has  shown  that  setting  PRINENDLINL  to  a  relatively  small 
number  like  4  (while  setting  PRINLEVEL  and  PRlNLENGTtl  to  NIL)  is  very  useful  particularly  due  to  tlie 
availability  of  die  continuation  facilities  described  below.  I  he  example  below  shows  how  an  example  of 
output  using  these  settings. 

(DEFUN  Roors-or- QUADRATIC  (A  B  C) 

(COND  ((NOT  (7ER0P  A)) 

(LET  ((DISCRIMINANT  (-  (*  B  B)  (•  4  A  C)))) 

(COND  ((PLUSP  DISCRIMINANT)  — - 

fruncation  of  die  output  can  also  be  triggered  by  typing  TERMINAL  STOP-OUTPUT.  This  inlcrrupLs  die 
prink  f  wuncdhtlciy,  cmimg  it  to  terminate  returning  normally. 

Wheneve;-  output  is  abbreviated  due  to  any  of  die  methods  describeil  above.  GPRINT  remcmbci'S  the  state 
of  the  printing  so  that  it  can  be  resumed.  Only  a  single  variable  is  inaintainetl  so  that  only  the  most  recently 
abbrevi.iicd  thing  is  rcniembercd.  If  printing  was  truncated  by  PRINENDLINL  or  user  iiitcrvention.  then  it  can 
be  conlinueil  from  the  ptiint  oftruneation  by  typing  tERMlNAL  RESUME. 

As  an  adilitumal  feature,  you  can  reprint  the  last  abbreviated  thing  in  full  with  PRINLEVEL,  PltlNt  ENGTH, 
PRINStARIi  INt.and  PRINENOLINE  abbreviation dis.ibled  by  typing  TERMINAL  1  RESUME. 

As  a  third  kind  of  abbreviation,  if  the  variable  GCHECKRECURSION  is  T  then  GPRINT  checks  for  circularity 
in  the  objects  it  is  printing.  When  a  circular  reference  to  an  object  is  cncoimtcrcd.  it  is  replaccil  in  the  output 
by  ''//  or  %/i.  x/i  is  only  used  in  a  list,  it  is  used  when  the  CDR  of  a  list  is  EQ  to  an  earlier  CDR  in  the  vumr  list. 
In  this  ease  /;  is  the  nuinber  of  CDRs  separating  the  two  positions,  is  used  in  other  situations.  Here.  « 
indicates  that  ri  selector  operations  (CAR.  CXR,  AREF;  but  not  CDR)  were  performed  between  the  first 
occurrence  of  the  object  and  this  one.  Iliis  kind  of  abbreviation  is  illustrated  below. 

the  result  of  (LET  ((X  ’(V  (Z  1  2  3)  4))) 

(RPLACD  (COR  X)  (CDR  X)) 

(RPLACA  (COAOR  X)  X) 

(RPLACA  (CDOADR  X)  (CADR  X)) 

(RPLACD  (CDDADR  X)  (CDAOR  X)) 

X) 

prints  as  (Y  (Z  ^2  ai  .  x2)  ,  XI) 

It  is  possible  (but  not  easy)  to  reconstruct  the  exact  shape  of  the  object  from  what  was  printed.  I  lowcvcr. 
the  main  imrposc  is  just  to  prim  something  more  readable  than  what  you  would  otherwise  sec.  An  important 
fcatiiK  ol  til  -  w.iy  this  abbreviation  is  done  is  that  it  is  completely  orthogonal  to  the  rest  of  die  forniattiug 
[iroci  ss  so  th.it  it  works  no  matter  what  kinds  of  ii.ser  formatting  fuiKtions  arc  written,  and  no  matter  what 
kinii  of  data  objwts  .ire  being  printed. 
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[Data  Types  Other  titan  Lists 

III  addition  to  lists,  GPRINT  has  built  in  formatters  for  all  of  the  standard  l.isp  daUi  types.  Syiiihols, 
niimhci\  strings,  and  tilings  of  random  types  not  specifically  discussed  below  are  treated  as  indivisible  atoms 
and  printed  in  the  standard  ways. 

Named  structures,  entities,  and  instances  are  printed  in  one  of  two  ways  depending  on  whether  or  not  tliey 
know  how  to  fonnat  Uieinselves.  If  tlic  object  accepts  the  message  :GFORMAT-SELF  then  GPRINT  sends  a 
:GFORMAT-SELF  message  with  the  object  as  argument  to  the  object  so  that  it  can  fomiat  itself. 

If  the  named  structure,  entity,  or  instance  dues  not  take  a  -.GFORMAT-self  message,  tlicn  GPRINT  treats  it 
as  an  atomic  objc'ct  and  lets  the  standard  printer  print  it.  'Hiis  makes  it  possible  to  use  GPRINT  on  these 
objects  without  having  to  write  fonnatters  for  titem.  However  it  should  be  noted  tliat  since  diey  arc  treated  as 
atomic  objects,  no  formatting  iKcurs  inside  tlicm  no  matter  how  large  their  print  foim  may  be.  l-or  example, 
a  line  break  will  never  be  inserted  inside  one. 

If  an  object  is  an  array  (and  not  a  named-structure)  it  is  formatted  as  follows.  GPRINT  first  checks  to  sec  if 
there  is  a  fonnatting  function  for  the  array.  'Ihe  association  between  fomiatting  functions  and  arrays  is 
maintained  through  a  list  of  functions  stored  in  titc  variable  6ARRAY-F0RMATTERS.  I'hcse  functions  arc  just 
like  Ihe  fonnatting  functions  described  above  except  that  in  addition  to  creating  qiienc  entries  in  order  to 
format  an  object,  tltcy  must  also  test  to  sec  whether  they  arc  applicable  to  the  objc'ct.  This  makes  it  possible 
for  the  user  to  use  any  kind  of  applicability  test  he  desires.  If  tire  format  function  is  applicable  it  should 
formal  the  object  and  return  T.  Otherwise  it  should  take  no  action  and  return  nil.  A  function  is  set  up  as  an 
array  fonnalter  by  adding  it  to  die  list  GARRAV- FORMATTERS.  GPRINT  calls  each  of  diese  functions  in  turn 
passing  it  the  object.  As  sikui  as  one  of  them  returns  T  it  slops.  If  they  all  return  NIL  dien  a  default  fomiatlcr 
is  used. 

The  default  array  fonnalter  first  prints  out  the  array  object  in  the  standard  way  (c.g.  .is  an  atom  conuiining 
the  type  and  the  address).  Next,  if  the  variable  CPRINT-ARRAY-CONTENTS  is  T  and  the  array  has  only  one  or 
two  dimensions  it  prints  otit  the  contents  of  the  array.  ITie  eontenLs  arc  printed  as  a  list  (for  one  dimensional 
arrays)  ttr  a  list  of  lists  (for  two  dimensional  ones).  Tabular  blocking  is  used  to  format  these  lists. 

Ihe  kind  of  arbitrary  user  specified  dispatching  .supported  for  arrays  is  also  supported  for  lists.  Functions 
put  on  the  list  Cl  IST-FORMATTERS  can  be  used  to  associate  formats  with  lists  when  the  association  is  based  on 
some  feature  other  than  the  CAR  of  die  list.  Similarly,  functions  pul  on  the  list  GSPECIAL- FORMATTERS  can  be 
uscrl  to  override  all  standard  dispatching  including  the  initial  split  based  on  data  type. 

Applicability  to  l^ingiiagcsOtherTlTan  Lisp 

It  is  important  to  note  dint,  though  the  discussion  above  was  cast  in  the  domain  of  die  I.isp  language,  dtc 
ideas  arc  substantially  programming  language  independent.  It  should  be  possible  to  use  these  ideas  to 
construct  a  flexible  pretty  printer  allowing  significant  user  control  of  format  in  any  programming  language 
environment. 

GPRINT  makes  it  iHissibIc  for  the  user  to  control  die  fonnat  of  both  programs  tiiid  data.  Of  diese  two 
capabilities,  the  control  over  program  formal  is  die  easiest  to  export  to  other  language  cnvironmcnt.s.  Two 
basic  things  arc  required:  a  represent, ilion  for  pn^ram  parse  trees,  and  a  mcdiod  whereby  die  user  can 
specify  fonnats  for  non-tenninal  nodes  in  these  trees.  In  languages  like  l  isp  where  a  data  representation  for 
parse  trees  is  part  of  the  definition  of  the  language,  this  is  the  logical  choice  for  dtc  representation.  In  other 
languages  M>mc  such  representation  h.is  to  be  developed.  IF  the  pretty  printer  is  intended  to  accept  program 
text  files  as  input,  a  parser  for  the  l.mp.tiage  has  to  lie  inipicmented  if  one  is  not  alicady  available. 

Iherc  arc  two  basic  ways  in  which  user  format  control  can  be  supplied.  One  way  is  to  use  the  same 
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incchnnisms  which  are  supplied  for  specifying  data  formats  by  simply  applying  them  to  the  data 
representations  for  parse  trees.  'Ibis  is  the  approtich  taken  by  GPRINT.  Another  approiich  is  to  follow  the 
suggestion  of  Oppen  [7]  and  allow  the  user  to  specify  formats  as  annotations  to  the  grammar  for  the 
programming  language.  From  die  point  of  view  of  implementation,  this  approach  is  essentially  identical. 
I  lowcver,  for  a  language  which  (unlike  Lisp)  has  extensive  syntax  tliis  appriKich  would  undoubtedly  be 
aesthetically  .superior  since  it  uses  stiindard  grammatical  notation  in  order  to  communicate  with  the  user 
instead  of  some  ad  hoc  internal  representation. 

Using  GPRINT's  approach  to  die  printing  of  data  in  other  programming  environments  is  more  difllcult. 
Ibe  key  issue  is  being  able  to  obtain  data  type  information  at  print  time.  However,  before  looking  at  this 
problem  in  detail  consider  some  other  issues. 

■|bc  form.ilting  templates  tlescribed  alxrve  could  be  u.scd  with  any  kind  of  data.  'Jbe  only  thing  which  has 
to  be  changed  is  diat  [  ]  has  to  be  extended  so  dial  it  can  decompose  other  composite  dati  structures  besides 
lists.  Logically  dicre  is  no  problem  since,  in  general,  any  dita  structure  has  a  dcfaidt  linear  ordering  for  its 
components,  l•rom  an  implementation  standpoint,  dterc  is  no  problem  with  selecting  out  components  one  at 
a  time  as  long  as  you  can  determine  die  data  type  of  a  given  structure. 

The  basic  dispatching  scheme  presented  above  can  be  straightforwardly  extended  as  long  as  type 
information  can  be  obtained.  It  is  easy  to  implement  an  association  between  types  and  formatting  routines  so 
diat  each  type  could  have  its  own  fonnat  Further  dispatching  on  subfcaturcs  of  individual  types  could  be 
implemented  if  desired. 

In  a  language  environment  such  as  I  isp  where,  in  general,  complete  run  time  type  information  is  available, 
it  is  trivial  to  dclenninc  (he  ty|w  of  something  when  it  needs  to  l)c  printed.  Unfortunately,  in  most  languages, 
much  of  the  vlata  type  information  is  used  only  by  die  compiler  and  is  not  available  at  run  time.  In  a  language 
with  pure  strong  typing  that  makes  it  possible  for  die  compiler  to  detennine  die  exact  data  type  of  every 
variable,  die  compiler  could  be  straightforwardly  modified  in  order  supply  the  type  infonnation  needed  by 
the  dispatcher.  One  way  to  do  this  would  be  to  have  the  compiler  create  a  table  of  type  information  which 
coulil  be  rcfcucd  to  by  the  dispatcher  at  run  lime.  Alternately,  die  dispatching  nccdcrl  for  indiv  idiial  calls  on 
the  printer  could  be  perfonned  at  compile  time  using  die  compile  time  type  infonnation.  In  order  to  make  it 
possible  for  die  user  to  inicraclivcly  request  the  printout  of  various  data  items  at  run  time,  the  tabular 
approach  wviuld  be  required,  just  as  a  dynamic  debugger  h.is  to  have  access  to  die  compiler’s  symbol  table  in 
order  to  use  the  programmer's  variable  names. 

Lfn  fortunately,  few  languages  have  pure  strong  typing.  Most  languages  support  data  ty  pes  such  as  union 
types  ami  variant  records.  Most  of  the  lime,  this  need  mM  be  a  severe  problem  because  sucli  ty|Ks  are  not 
useful  unless  there  is  some  way  for  programs  to  determine  whiit  the  actual  type  of  a  daui  item  is.  For 
example,  the  compiler  could  specify  to  the  dispatcher  diat  a  given  data  item  was  of  a  particular  union  type. 
Hie  programmer  would  have  to  supply  a  decision  procedure  which  could  be  used  by  dir  dispatcher  to 
detenuine  the  exact  type  of  the  data  item  at  run  time.  Ihis  would  not  be  a  difTicuit  tisk  as  long  as  the  union 
type  w.is  straightforward  and  a  single  decision  pnxedurc  for  the  union  type  could  be  implemented  which 
would  work  ill  all  situations. 

I  hcrc  arc  language  environments  (for  example  as.scmblcr  language)  which  have  little  run  time  type 
information,  lit.li.  compile  time  type  constraints,  and  where  the  user  dcAiicd  iliita  structure's  arc  (’flen  of  such 
a  chaotic  naiurc  diat  it  would  be  virtually  impossible  to  write  the  kind  of  data  type  decision  pmccdiircs 
needed  by  the  dispatcher.  In  such  a  situation,  the  kind  of  pretty  printer  presented  in  Ihis  paper  would  not  bo 
oraciical.  It  should  be  noted  that  such  an  uncontrolled  eiiviitinmcnt  presents  a  number  t'f  problems  nnicli 
more  serious  tlt.in  the  inapplicability  of  this  kind  of  pretty  printing.  Current  (rends  have  been  toward  more 
rcguinri/cil  environments  which  should  be  able  to  support  a  pretty  printer  like  GPRINT. 
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Conclusion 

GPRINT  includes  a  large  number  of  standard  formats  and  features  (such  as  die  ones  used  as  examples 
above).  As  a  result,  a  user  docs  not  have  to  write  any  of  his  own  formats  in  order  Ui  get  reasonable  output  in 
ordinary  situations.  However,  no  amount  of  anticipation  can  satisfy  every  user.  Hiis  is  particularly  true  when 
a  pretty  printer  is  being  used  in  an  interactive  programmii>5  environment  to  print  data  as  well  as  programs, 
and  when  it  is  called  by  user  programs  as  well  as  by  the  system  itself. 

Hie  principal  goal  of  the  design  of  GPRINT  has  been  to  produce  a  system  with  good  human  engineering 
which  gives  the  user  powerful  facilities  for  controlling  the  formal  o  'output  and  which  at  the  sttmc  time  makes 
the  specification  of  simple  formats  simple.  Two  key  ideas  comprise  GPRINT's  approach  to  this  problem:  die 
basic  algorithm  chosen,  and  die  existence  of  multiple  levels  at  which  a  user  can  specify  foniiatting 
infonnation. 

Ilie  key  features  of  the  algorithm  underlie  the  basic  simplicity  of  GPRINT's  approach  and.  at  the  same 
time,  fundamentally  limit  its  scope.  'Hie  division  of  die  algoridim  into  two  pieces  communicating  dirough  a 
queue  makes  it  possible  to  separate  the  simple  parts  of  the  algoridim  from  the  complex  ones.  The  decision  to 
use  a  linear  time  algoridim  in  the  output  routine  makes  it  possible  for  GPRINT  to  run  with  acceptable  speed. 
However,  it  fundamentally  limits  the  kind  of  foniiatting  decisions  which  can  be  made  by  die  output  routine. 
In  particular,  when  making  its  decisions,  it  can  only  huik  ahead  a  very  limited  distance.  An  example  of  diis 
was  discussed  in  die  section  on  tabular  form  output 

In  line  with  the  limited  abilities  of  die  output  routine  the  queue  entries  arc  designed  so  diat  they  encode 
essentially  only  two  fonnatting  options  for  a  given  structure:  how  to  print  it  on  one  line,  and  how  to  print  it  on 
multiple  lines.  (A  third  miser  fonnat  is  also  specified  for  each  structure,  however,  this  fonnat  is  largely 
implicit  and  the  user  docs  not  have  very  much  control  over  it.)  'Hiis  design  is  an  important  basis  for  die 
undcrsiandability  of  die  primer  because  it  presents  die  user  with  a  simple  model  of  how  fonnatting  decisions 
are  made.  I  lowcvcr.  one  could  easily  imagine  wanting  to  specify  more  complex  formatting  infomiaticm.  1^ 
example,  one  might  want  to  speeily  two  completely  dilferenl  multi-line  formats:  one  to  usi  when  there  is  a  lot 
of  room  available  and  die  other  to  use  when  dicrc  is  only  a  little  space. 

'Hie  printer  provides  diree  basic  levels  at  which  a  user  can  specify  formatting  infonnation.  l-'irst,  he  can 
simply  use  the  default  fonnats  supplied  with  die  printer  and  docs  not  have  to  do  anything  himself.  Second, 
he  can  use  simple  templates.  'Hiesc  make  it  very  easy  for  him  to  describe  certain  aspects  of  how  a  structure  is 
to  be  Ibnnatted.  Third,  he  can  write  more  complex  formatting  functions.  Iliis  allows  him  to  exercise  much 
more  control  over  the  format  to  be  used,  at  die  cost  of  greater  complexity. 

'The  use  of  multiple  levels  of  intcniction  is  a  generally  useful  technique  for  increasing  the 
undcrsiandability  and  availability  of  a  system  to  a  wide  range  of  users.  It  makes  it  possible  for  users  who  have 
simple  needs  to  satisfy  them  without  having  to  learn  very  much  about  the  system.  Users  who  take  the  dmc  to 
learn  more  can  then  do  more. 
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Maclisp  Compatibility 

I  he  discussion  in  the  main  body  of  this  paper  is  couched  in  tenns  of  l.isp  Machine  Lisp,  however,  GPltlNf 
is  substantially  Maclisp  cutnpalible.  Almost  everything  above  applies  equally  to  both  versions.  Ibis  section 
discusses  the  few  dilTcrcnccs  between  the  two  versions. 

The  I/O  in  Maclisp  is  quite  different  than  on  the  Lisp  Machine.  The  Maclisp  version  follows  all  of  the 
MrKlisp  conventions,  in  particular,  you  can  call  6PRINT  with  a  list  of  files  and  default  output  is  controlled  by 
the  variables  TYO,  ^W,  OUT  FILES,  etc. 

The  compilation  environment  is  somewhat  different  in  Maclisp.  GPRINT  must  he  loaded  in  in  order  tor 
formatting  functions  to  compile  correctly  because  GF  is  a  macro.  On  the  I  .isp  Machine  you  don't  have  to  take 
any  special  action  in  order  fur  this  to  be  die  case  when  you  arc  using  GPRINT.  In  Maclisp  you  have  to  make 
sure  that  it  is  loaded  into  the  compiler  by  a  DECLARE  in  any  file  which  defines  formats.  Also  note  tliat  in 
Maclisp  die  functions  which  take  optional  control  parameters  (eg  GPRINT.  GPRINTl,  GPRINC,  GEXPLODE,  and 
GEXPLODEC)  arc  Icxpnj  and  need  *LEXPR  declarations. 

In  Maclisp,  the  functions  uiggered  by  TERMINAL  STOP-OUTPUT  and  TERMINAL  RESUME  are  triggered  by 
typing  control  characters.  The  printer  can  be  stopped  by  typing  ^S.  Printing  can  be  resumed  by  typing  ■'C 
t/'R  in  rOI‘S20  versions).  ILcprinting  in  full  is  triggered  by  '^P.  In  Maclisp  diesc  control  characters  arc  not  set 
up  by  default.  You  have  to  call  the  function  6SET-UP-PRINTER  in  order  to  get  them  defined.  Note  also  diat 
in  Maclisp,  die  default  symbol  for  depth  abbreviation  is  "X'"  instead  of 

I'he  Maclisp  version  of  GPRINT  supports  the  fonnalting  of  hunks.  Two  basic  mechanisms  arc  supplied 
analogous  to  die  ones  described  for  arrays  in  the  main  body  of  the  paper.  If  a  hunk  is  a  USRHUNK  which  takes 
nics.sagc-s  (note  diat  EXTENDS  and  the  like  arc  all  USRHUNKS)  dicn  GPRINT  checks  the  messages  it  accepts.  If  it 
lakes  die  message  :GFORMAT-SELf  dicn  GPRINT  sends  a  :GFORMAT-SELF  message  with  the  object  as 
argument  to  the  object  so  diat  it  can  fbnnat  itself.  If  a  USRHUNK  docs  not  lake  a  •  GFORMAT-SELF  message,  but 
it  diKS  Like  a  :  PRINT-SELF  or  PRINT  message  then  GPRINT  treats  die  hunk  as  an  atomic  object  and  lets  the 
standard  printer  print  it.  If  a  USRHUNK  docs  not  accept  any  of  dicsc  messages,  then  it  is  treated  as  an  ordinary 
hunk. 

In  order  to  format  an  ordinary  hunk  GPRINT  first  checks  to  sec  if  there  is  a  formatting  hinction  for  the 
hunk.  The  user  scLs  up  a  hunk  formatter  by  adding  a  function  to  the  list  in  the  variable  GHUNK- FORMATTERS. 
I'he  purpose  of  this  function  is  two  fold;  to  test  whether  it  is  applicable  to  a  hunk  (in  which  case  it  returns  f) 
and  in  this  case  to  actually  format  the  hunk.  GPRINT  calls  each  of  these  functions  in  turn  passing  it  die  hunk. 
As  STMiii  as  one  of  them  returns  T  it  stops.  If  dicy  all  return  NIL  then  die  hunk  is  printed  by  default  in  the 
nomial  way  (c.g.  in  parentheses  widi  die  CXRs  separated  by  pcriixls)  in  block  format. 
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Functional  Summary 

I  'his  appendix  describes  all  of  the  user  fiinctions  supported  by  GPR IHT. 

GPRINT  o6/<'(7&opt  tonal  stream  format  level  length  emlline  startline 

lliis  is  exactly  analogous  to  PRINT  except  that  it  dt)cs  pretty  printing.  Ilic  first  argument  is  the  object 
to  be  printed.  ITic  second  argument  specifics  the  stream  to  use  for  output  If  it  is  missing  then  the 
standard  system  default  is  used  (c.g.  STANDARD-OUTPUT). 

I'hc  tliird  argument  is  a  formatting  function  which  defaults  to  NIL.  if  non-NIL  it  will  he  used  by 
GDISPATCH  to  fonnat  the  object  h»r  example.  (GPRINT  FDD  STANDARD-OUTPUT  ’  :GFN-FORMAT) 
will  use  functional  format  for  the  top  level  of  FDD  nr)  matter  what  the  CAR  of  ftK)  is.  The  last  four 
arguments  can  he  used  to  control  abbreviation.  They  arc  used  to  set  tlie  values  of  PRINlEVEL. 
PRINLENGTH,  PRINENOLINE,  and  PRINSTARTLINE  respectively.  If  tlicy  arc  omitted,  then  tlie  current 
bindings  of  these  variables  arc  used  to  control  abbreviation. 

GPRINTl  oi/rct  &optional  stream  format  level  length  eiuiline  startline 

This  is  exactly  like  GPRINT  except  tliat  it  corrr'sponds  to  PRINl  instead  of  PRINT.  (Unfortunately,  tiic 
standard  Maclisp  grind  package  has  already  used  up  the  name  GPRINl.) 

GPRINC  o/)/V</&optiona1  stream  fonnat  level  length  emlline  starlline 

This  is  exactly  like  GPRINT  except  that  it  corresponds  tt)  PRINC  instead  of  PRINT. 

PL  ohirct  &optiona1  stream  format 

This  is  an  abbreviation  for  (GPRINT  object  file  format  NIL  NIL  NIL  NIL).  It  specifies  that  the  object 
should  he  printed  without  abbreviation.  It  is  quite  handy  at  top  level. 

GFORMAT  siiiaiii  template &rest  args 

This  is  just  like  FORMAT  except  that  GPRINT  is  called  to  do  die  printing  and  the  template  has  tlic  same 
form  as  a  template  for  GF.  I'or  example,  (GFORMAT  NIL  “(•_<•->)"  X)  creates  a  string  containing  X 
printed  in  functional  formal  at  die  top  level. 

GEXPLODE  (ihiect  &optional  Jhnnat  level  length 

I  his  is  analogous  to  the  function  EXPLODE  except  that  it  docs  pretty  printing. 

GEXPLODEC  object  &opt1ona1  fonnat  level  length 

I  bis  is  analogous  to  the  function  EXPLOOEC  except  that  it  dtKS  pretty  printing. 

PLP  Aquote  &rest  args 

I  his  is  very  similar  to  GRINDEF  but  calls  GPRINT.  Ivach  arg  is  cither  a  symbol  or  a  CONS  of  a  symbol 
and  a  list  of  specific  properties  to  print  If  it  is  a  symbol  then  any  properties  it  has  which  arc  in  the  list 
PLP -PROPERTIES  arc  printed.  Otherwise,  the  specified  properties  arc  printed.  If  no  arc  supplied 
then  PLP  is  recxccutcd  on  the  last  set  of  args  it  was  called  on. 

GSET-UP-PRINTER 

Calline  this  sets  up  GPRINT  as  the  lop  level  printer.  I’his  consists  basically  of  just  setting  tlic  variable 
PRINl  loGPRI.'JTl. 
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CF  lemplaletir 9St  args 

I'his  is  used  lu  dcHnc  formatting  fVinctions.  'Ihc  structure  of  tire  templaie  is  suininari/.cd  in  a  separate 
appendix.  Note  that  unlike  GFORMAT  this  dues  not  actually  print  anything.  Rather,  it  just  makes  queue 
entries  when  the  formatting  function  it  is  in  is  called  by  GDISPATCH.  The  fact  that  GF  is  a  macro  saves 
time  by  parsing  the  template  at  compile  time,  and  producing  efHcicnt  code  to  do  the  formatting.  ’Ihis 
docs  waste  space  however.  It  is  to  your  advantage  to  make  each  template  as  sliort  as  possible. 

GFUNCTION  template 

Ihis  is  an  abbreviation  for  s* '( LAMBDA  (X)  (GF  tcmplatet)). 

FORMAT  stream  format-string  Arest  args 

A  new  fonnat  keyword  ~N  is  defined  so  that  you  can c<i1l  GPRINTl  from  FORMAT.  xiN  invokes  GPRINC. 
Numeric  pre-arguments  arc  taken  to  be  PRINLEVEL,  PRINLENGTH.  etc. 
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Variable  Summary 

lliis  appendix  summarizes  all  of  the  control  variables  which  can  be  set  by  die  user  in  order  to  control  the 
actions  of  GPRINT. 

PRINLENGTH  system  Jejined  default 

'I1iis  specifies  the  maximum  length  list  that  will  be  printed  without  abbreviation.  NIL  means  inrinity. 
PRINLEVEL  system  defined  default 

This  spccirics  the  maximum  depth  at  which  any  object  will  be  printed.  NIL  means  infinity. 
PRINSTARTLINE  default  UlL 

Output  is  inhibited  until  the  PRINSTARTLINEth  line  is  reached.  NIL  is  the  same  as  0. 
PRINENDLINE(/c/au/r4 

Output  is  aborted  and  the  printer  returns  nonnally  as  soon  as  the  PR  INENDLINEtli  line  is  reached. 
PRINMARGIN^A’/zu/ZNIL 

I'his  specifies  tlic  total  line  length  available  for  printing.  If  it  is  NIL,  then  the  printer  asks  the  output 
stream  what  the  line  length  is. 

HISW-VIDIH  default  AO 

Miser  nuKlc  printout  is  triggered  if  there  is  less  than  this  amount  of  width  available  for  printing. 
HAJOR-WIOTH  default  40 

I  ell  shifling  oflogical  units  will  occur  if  there  is  less  than  this  amount  of  width  available  for  printing. 
GCMECKRECURSION  default  T 

If  Uiis  is  T  tlicn  GPRINT  checks  for  circular  pointers  and  abbreviates  them  appropriately. 

G.SII0W-  E  RRORS  default  NIL 

Normally,  GPRINT  docs  an  ERRSE  r  so  diat  no  error  which  occurs  during  fonnatling  can  cause  an  error 
in  GPRINT.  If  this  is  set  to  T  dicn  you  will  enter  the  error  handler  if  any  error  occurs.  This  is  useful  for 
debugging. 

6F0RCE-M0RES  default  T 

If  this  is  r  dicn  things  arc  set  up  so  that  you  get  MORE  processing  all  of  die  dmc.  Odicrwisc,  MORE 
processing  is  suppressed  if  prindng  is  initiated  widiin  7  lines  of  the  bottom  of  the  screen. 

GSPEC I AL- FORMATTERS  default  NIL 

I  his  holds  a  list  of  fonnatting  functions  which  are  tested  for  applicability  before  any  other  dispatching 
is  done. 

G0VrRRIDING-LIST-F0RMATTERS(fe7!iu/rNIL 

This  holds  a  list  of  formatting  functions  which  arc  tested  for  applicability  to  any  list  which  is  being 
printed  before  any  odicr  dispatching  is  done  on  it 
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GLIST-FORMATTERS  default  Hll 

lliis  holds  a  list  of  fornuilting  functions  which  arc  tested  for  applicability  to  any  list  which  is  being 
printed  before  any  other  dispatching  is  done  on  it  unless  dispatch  was  called  with  a  specific  suggesting 
of  how  to  format  the  lisL  (  Hie  diflcrencc  between  this  and  GOVERRIDING-LIST-FORMATTERS  is  that 
these  arc  applied  in  fewer  places.  For  example,  they  will  not  be  tested  against  tire  list  of  bound 
variables  in  a  PROG  liecause  the  format  for  PROG  specifies  exactly  how  tliis  subpart  of  a  PROG  should  be 
fonnatted.) 

iGFORMAT  property 

If  the  CAR  of  a  list  has  a  value  for  tliis  property,  then  the  value  is  called  as  a  fonnatting  function  to 
format  the  lisL  (If  none  of  the  above  cases  apply.) 

GAPPLY-FORMAT  default  :GAPPLY-FORMAT 

'Ibis  is  used  as  tlie  format  for  literal  LAMBDA  applications. 

GFM-FORMAT  default  :GFN-FORMAT 

Hus  is  used  as  die  default  foimat  for  hinction  applications. 

GSYMBOL-CAR- FORMAT  default  -.GITBLOCK 

This  is  used  as  die  default  format  for  lists  whose  CARS  arc  symbols. 

GNON’SYMSOL'CAR'FORMAT  default  iCUBlOCK 

Ibis  is  used  as  die  default  funnat  fur  lists  whose  CARS  arc  nut  symbols. 

:GFORMAT-SELF  message 

If  an  instance,  entity,  or  named-structure  is  set  up  so  that  it  will  process  tliis  mcssiigc  type,  then  it  is  sent 
a  mes.sagc  in  order  to  format  itself.  It  gets  one  argument  (the  object  itself)  in  addition  to  any  arguments 
which  are  supplied  by  the  message  sending  mechanism. 

GARRAY- FORMATTERS  default  NIL 

ibis  holds  a  list  of  formatting  functions  which  will  be  tested  for  applicability  to  any  array  being  printed 
which  doesn’t  take  a  :  GFORMAT-SELF  message. 

GHUNK-FORMATTERS  default  NIL 

'Ibis  holds  a  list  of  formatting  functions  which  will  be  tested  for  applicability  to  any  hunk  being  printed 
which  doesn’t  take  a  :  G FORMAT  -  SELF  message. 

GRIND-MACROEXPANOED  default  Hll 

If  diis  is  T  Uicn  MACROMEMOii'Cd  macros  will  printed  out  as  dicy  appear  after  expansion.  Otherwise  they 
will  be  printed  out  as  they  appear  before  expansion. 

PLP-PROPERTIES  default  ( :  FUNCTION  :  VALUE) 

riiis  holds  the  list  of  values  which  die  hinction  PLP  will  print  out  by  default  'The  default  specifies  that 
only  tlie  function  value  and  value  should  be  printed. 
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Summary  of  Formatting  Codes 

'lliis  appendix  summarizes  the  fonnatting  codes  which  arc  available  fur  use  in  Utc  template  supplied  to  the 
macro  GF.  'Iltc  template  Is  a  string  of  single  character  commands,  some  of  which  can  be  followed  by  a 
parameter.  'Ilicrc  arc  three  kinds  of  parameters: 

n  ■  Some  commands  take  a  number  as  a  parameter.  Ibis  number  should  be  an  integer  optionally 
beginning  with  a  and/or  ending  with  a  Alternately,  it  can  be  omitted  in  which  ease  a 
default  value  is  used. 

/  -  Some  commands  take  a  function  name  as  a  parameter.  Ibis  name  is  an  arbitrary  symbol  possibly 
containing  " : ".  Case  does  not  matter.  'Ibe  symbol  must  be  terminated  by  a  blank.  Function  name 
parameters  cannot  be  omitted.  They  have  no  default  values. 

#  -  Ibis  can  be  used  in  phKe  of  any  numeric  parameter  or  any  hinction  name  parameter.  It  indicates 
that  the  next  input  to  GF  should  be  used  as  the  parameter,  instead  of  a  literal  value. 

'Ibe  commands  which  can  be  used  in  a  template  are  divided  into  several  categories.  'Ibe  first  set  is  used  to 
parse  die  stnicture  of  the  arguments  to  GF  so  that  titcir  parts  can  be  accessed. 

[  ]  -  Ibis  is  used  to  access  the  internal  elements  of  an  item  which  is  a  list  'Ibe  template  inside  the 
brackets  refers  to  the  elements  of  the  list  If  the  item  is  not  a  list  tlicn  no  fonnatting  of  it.  or 
anything  inside  it,  is  done.  PrcKessing  begins  by  considering  each  element  of  this  list  in  turn.  As 
soon  as  the  list  is  exhausted,  control  skips  (Hit  of  the  subtemplatc  and  continues  after  its  end.  Ibis  is 
done  even  if  tlicre  is  more  stuff  left  in  tlic  subtemplate.  Special  code  is  included  to  deal  with  the 
possibility  of  unexpectedly  encountering  a  non-NIt  atomic  CDR.  If  this  happens  it  is  automatically 
formatted  to  appear  after  a  []  tilso  pnxiuccs  special  code  to  deal  with  Icngtli  abbrevitition. 
Ibcy  only  way  to  get  it  automatically  is  to  use  []. 

.  '(Period)  'Ibis  is  valid  only  inside  [].  It  spcciftcs  tliat  the  next  item  is  die  whole  sublist  left  to 
process  by  []  rather  Uian  its  CAR.  For  example,  (GF  "[*_.*]"  ’(1  Z))  is  the  same  as 

(GF  1  '(2)). 

Note  that  when  a  " . "  is  used,  normal  checking  for  the  end  of  the  list  in  the  [  ]  is  suppressed.  For 
example,  (GF  '(!))  is  equivalent  to  (GF  1  NIL).  Ibe  NIL  .it  the  end  of  the 

list  is  explicitly  picked  up  by  the  and  a  blank  will  be  printed  at  the  end.  Ibis  happens  even 
though  the  []  template  would  normally  have  terminated  right  after  the  first  •. 

<  >  -  'Ibis  can  only  be  used  directly  inside  []  (or  ()).  It  specifies  an  indefinite  rcpeirt  block.  Ibis  is 
used  to  specify  a  template  for  a  list  of  unknown  length. 
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llic  next  set  of  commands  arc  used  to  specify  how  individual  items  arc  printed  out 

I  -  Ignore  the  corresponding  item. 

'liieral'  -  Print  the  indicated  literal  using  PRINC  and  do  not  count  it  as  one  of  the  items  printed  from 
the  point  of  view  of  length  abbreviation.  Note  that  in  the  Uleral . stands  for "  ’ ". 

•  -  This  specifics  that  GOISPATCti  should  be  called  in  order  to  format  the  corresponding  item. 

Xf  -  lliis  specifics  tliat  the  function  /  should  Ik  called  in  order  to  fonnat  die  corresponding  item. 
(Note  if  /  is  d*  tlicn  tlic  argument  which  is  used  as  the  function  follows  die  argument  which  is 
Ibnnatted.) 

$/- (Dollar  sign)  Tliis  command  specifics  diat  GDISPATCH  should  be  called  in  order  to  fonnat  die 
corresponding  item,  but  that  the  function  /  slunild  be  passed  to  GDISPATCH  as  a  suggestion  of  how 
to  fonnat  die  item.  (Note  if  f  is  M  dicn  die  argument  which  is  used  as  die  function  follows  the 
argument  which  is  formatted.)  'Die  difference  iKtwccn  $/  and  Xf  is  that  with  $/  GDISPATCH  gets 
control.  As  a  result,  if  the  item  is  not  a  list,  or  if  some  function  on  GOVERRIDING-LIST- 
FORMATTERS  formats  it.  then  the  function /  will  not  get  used. 

%/”subtmphte/''  -  In  addition  to  die  name  of  a  function,  the  parameter  to  $  can  be  a  literal  template 
which  is  eonverted  into  a  function  to  use.  (Note  (hat  die  quotes  have  to  be  slashified  in  order  to 
read  in  inside  a  quoted  string.)  Hie  formatting  fiiiKtion  produced  is  compiled  nut  of  line.  As  a 
result,  if  there  is  a  «  format  code  in  it.  die  argument  to  GF  diat  this  refers  to  will  be  compiled  tuit  of 
tine.  In  order  for  dtis  to  work  any  variables  this  refers  to  must  be  declared  special. 

■fhe  next  commands  arc  used  to  specify  the  nested  structure  of  the  initput  (which  need  not  be  die  same  as  that 
of  die  input). 

(H  )  -  ’lliis  indicates  a  substructural  unit  in  the  output,  llte  parameter  specifics  what  indentation  to 
use  when  printing  out  die  items  inside  die  substaicturc  if  the  substructure  cannot  be  printed  on  a 
single  line.  (If  the  indentatitin  is  specified  to  be  rero  dicn  die  substructure  is  not  counted  as 
increasing  die  depth  from  the  point  of  view  of  depth  abbreviation.)  fhe  default  parameter  value  is 
calculated  as  the  sum  of  the  lengths  of  the  first  thing  printed  in  the  substructure,  and  any  literals 
before  it  and  any  s|iaccs  alter  it. 

■  (Plus)  'Ihis  specifies  a  change  in  indentation.  1lic  indentation  level  in  the  current  substructure  is 
incremented  by  n  which  can  be  negative.  Note  that  diis  will  not  take  effect  until  the  next  line.  For 
example,  the  template  ''(•-•-■rz*-*)"  docs  not  increase  die  indentation  until  the  fourth  item  is 
printed  while  "(*-•>2 -•-•)''  prints  the  third  item  at  an  increased  indentation. 

( //  )  -  'lliis  is  a  useful  abbreviation  in  the  situation  where  the  nested  structure  of  the  output  is  the  same 
as  the  nested  stnicturc  of  the  input,  and  when  you  want  to  print  parcndiescs  around  die  structure.  It 
is  an  abbreviation  for  (n '  ( '  [  ]')’}.  Additionally,  if  the  ( n  )  is  nested  more  directly  inside  [] 
than  inside  $  then  it  is  treated  as  an  abbreviation  for  $/"{»'('[  ]')')/".  In  other  words,  if  the 
item  whose  format  is  being  sjiccificd  by  die  (n  )  was  not  passed  through  GDISPATCH  for 
dispatching  then  die  $  format  code  is  used  to  force  the  list  to  dispatch  thniugh  GDISPATCH.  ’lliis 
prevents  (he  format  from  blowing  up  wIku  the  item  is  nut  a  list.  (Note  die  comment  about  #  inside 
$/"  /"above.) 
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llic  next  set  of  commands  spcciHcs  spacing  and  where  and  when  carriage  returns  should  be  printed.  Note 
that  there  is  actually  a  complete  separation  between  these  two  concepts.  'Ibe  format  codes  used  above  which 
combine  the  two  ideas  are  abbreviations  combining  the  underlying  codes. 

~/i  -  (  Tilde)  Print  n  (default  1)  spaces.  (Note  that  spaces  arc  elided  if  they  arc  the  first  or  last  tiling  on  a 
line). 

Tn  -  Tab  over.  Moves  to  a  place  where  the  character  position  relative  to  the  current  indentation  is 
congruent  to  zero  modulo  n.  (Docs  not  move  at  all  if  it  docs  not  have  to.)  When  necessary,  a 
default  tab  size  is  calculated  based  on  the  length  of  the  other  items  in  the  substructure. 

A  -  IX)  a  line  break  here  always. 

I  -  Same  as  A. 

N  -  Do  a  line  break  here  if  required  for  normal  mtxlc  printing.  I.c.  if  and  only  if  the  structure 
immediately  containing  this  point  cannot  be  printed  on  a  single  line. 

-n  -  (Minus)  Abbreviation  for  "~»N”  which  is  what  you  usually  want 

B  -  IX)  a  line  break  here  if  required  for  block  mode  printing.  'Hiis  is  the  same  as  N  except  that  even  if 
tlie  immediately  containing  structure  is  being  broken  up  a  line  break  will  not  be  put  here  as  lung  as 
tlie  following  structure  can  be  printed  on  the  end  of  the  current  line  and  the  prior  structure  at  this 
level  was  printed  on  a  single  line. 

,  n  -  (Comma)  Abbreviation  for  '*~n8"  which  is  what  you  usually  want 

:  n  -  (Semicolon)  Abbreviation  for  *'~1ThB"  which  is  what  you  often  want. 

M  -  IX)  a  line  break  here  if  required  for  miser  mode  printing.  Put  a  line  break  here  if  tlie  containing 
structure  will  not  fit  on  a  single  line,  and  the  remaining  line  widtli  available  for  printing  is  less  tlian 
MISER-WIDTH. 

_/i  •  (Underscore)  Abbreviation  for  which  is  what  you  usually  want 

Tlie  next  two  formatting  codes  were  not  discussed  above.  11icy  arc  provided  ns  extra  hooks  into  the 
GPKINTing  process. 

AZ-’Ihe  function /is  called  with  no  arguments  at  this  point  Note  that  function  Ls  called  during  die 
fomiatting  process. 

E  -  When  the  output  routine  gets  tn  this  point  in  printing,  the  arg  to  GF  corresponding  to  the  It  is 
E  VALed  (out  of  line).  'Iliis  is  useful  for  getting  information  about  the  suite  of  the  printing  process.  It 
should  NQT  be  used  to  print  anything  out  because  the  output  routine  will  not  realize  that  anything 
was  printed  and  its  character  position  calculations  will  be  wrung.  Note  that  the  difference  between 
&  and  E  is  the  time  at  which  the  functioti  evaluation  occurs. 

'Die  characters  SPACE,  TAB,  CR.  and  LF  arc  all  ignored.  Any  other  character  is  an  error. 


